WARMABS

An alternative method for fitting XSTAR results to observed spectra within xspec is to use the xspec “analytic” model warmabs. This actually includes several separate models: warmabs, photemis, hotabs, hotemis, and multabs. These provide xspec models for warm absorbers and photoionized emitters, and for coronal equilibrium absorbers and emitters without requiring construction of \(\texttt{mtables}\) or \(\texttt{etables}\). The models use pre-calculated “population files” which are standard xstar output files that store information on charge state distributions, level populations, line emissivities etc. The warmabs models then calculate synthetic spectra from these files, basically skipping all the steps associated with solving the rate equations. This approach has several advantages:

First, it circumvents the intrinsic approximations associated with use of tables for absorption with variable abundances treated as multiplicative parameters (see Variable Abundances in Table Models). Warmabs/photemis/windabs/multabs calculate spectra using stored level populations which are then scaled using element abundances specified during the xspec session before the spectra are calculated. Therefore the approximations associated with the use of tables are avoided. (However, see the section below on the current limitations of these models).

Second, the provide the ability to use arbitrary spectral resolution, not limited by the internal xstar spectral resolution or the fixed energy grid at the time of table creation. Finally, they allow the use of turbulent broadening as a fitting parameter in xspec.

Limitations of these models are:

Most importantly, it calculates the spectrum ‘on the fly’, appropriate to the energy grid and parameters the user specifies. But it does not calculate the ionization balance self-consistently. It uses a saved file of level populations calculated for a grid of optically thin models calculated with a \(\Gamma=2\) power law ionizing spectrum. So this will not be self-consistent if your source has a very different ionizing spectrum. Also it implicitly assumes that the absorber has uniform ionization even if you specify a large column, which is not self-consistent.

It is also not blindingly fast. On a 1 GHz machine, the first time ‘mo warmabs ..’ is typed, the initial setup requires \({\sim}30\) seconds. After that, each time an abundance or ionization parameter is changed, it requires 5-10 seconds to recalculate the model.

Similar to a classic tabulation the population files store charge state and level populations on a grid of ionization parameters. We expect the resolution of \(\log\xi\) to be sufficient for most of the time but the user should be aware that there is an internal discretization with regard to ionization parameter and some cases may require recalculation of the population files using a smaller stepsize in \(\log\xi\).

Whether photemis takes into account continuum photoexcitation or not will depend on the value of the cfrac parameter used in calculating the populations files. As with an xstar calculation, cfrac=1 ignores continuum photoexcitation and cfrac=0 includes it. The standard populations files distributed with warmabs use cfrac=0.

This package is under constant development. Some embarrassing bugs have already been found, but more may still lurk. Please contact the helpdesk with any reports or questions.

Obtaining warmabs

The warmabs package is not included as part of the standard xstar distribution within heasoft. Instead, it must be downloaded and installed separately from the FTP site. The current release can be obtained from:

https://heasarc.gsfc.nasa.gov/FTP/software/plasma_codes/xstar/warmabstar.tar.gz

The contents of the tarfile include:

atdbwarmabs.fits
xstar atomic database binary fits file. This must reside in directory pointed to by the WARMABS_DATA environment variable. This file has the same format as the atdb.fits file used by xstar, but is kept distinct. This is important because the structure of the populations files (described below) depend on the version of the atomic data used in the run which created them. Thus warmabs must use the same version of this data file as was used in the calculation of the population files. In spite of the revision process, by which we try to keep the release versions of this file used by xstar and warmabs the same, it is possible for the two to get out of sync. If this happens unpredictable, incorrect, and not necessarily fatal errors may occur. The user should beware of this potential problem.
coheatwarmabs.dat
compton heating/cooling data file. This must reside in directory pointed to by WARMABS_DATA environment variable. This file is identical to the file coheat.dat which is part of xstar.
fphotems.f
source code for warmabs, photemis, multabs, hotemis, and hotabs
lmodel_warmabs.dat, lmodel.dat
local model definition file needed by xspec.

PARAMX
file containing parameter statements setting array dimensions needed by fphotems.f
README
additional information

Installation

The procedure for setting up and using this model is as described in the xspec manual. You need to have the heasoft package installed on your machine, but it must be built from source. Local models cannot be installed from a binary installation.

Download and untar this directory somewhere in your user area

wget https://heasarc.gsfc.nasa.gov/FTP/software/plasma_codes/xstar/warmabs247.tar.gz
tar xfz warmabs247.tar.gz

Setup and initialize the HEADAS environment:

export HEADAS=</path/to/your/headas/>
source $HEADAS/headas-init.sh

Set the WARMABS_DATA enviroment variable to point to the location of the population files, atomic database and Compton heating file:

export WARMABS_DATA=`pwd`

Start xspec and compile warmabs inside xspec or just pipe the compile command to xspec.

echo "initpackage xstarmod lmodel.dat $WARMABS_DATA" | xspec

After the build is complete, the model can be loaded in xspec using the lmod command. The WARMABS_DATA environment variable needs to be defined whenever warmabs is used.

XSPEC12>lmod xstarmod </path/to/installation>

In subsequent sessions you don’t neet to do the initpackage step again, just lmod and WARMABS_DATA.

warmabs

Inside of xspec, the model can be invoked by typing

XSPEC12> mo warmabs*pow

or variations on that. The input parameters include:

column: Log of the absorption column density in units of \(10^{22}\,\text{cm}^-2\).
rlogxi: Log of the ionization parameter. See Log of the ionization parameter (rlogxi) for details.
Cabund...Znabund: Elemental abundance relative to the xspec abundance table for elements C though Zn.
write_outfile: Switch to write information of the strongest 500 lines to a FITS file.
outfile_idx: Integer number to index the output FITS files. Useful if more than one warmabs component is used.
vturb: Turbulent velocity broadening. See Turbulent Velocity (vturbi) -hidden for details.
Redshift: Redshift applied to the whole model.

photemis

The photoionized emitter can be invoked by typing

XSPEC12> mo photemis

This model is the ‘thermal’ (i.e. recombination and collisional excitation) emission which comes from the same plasma used in warmabs. Note that this does may or may not include the effect of continuum photoexcitation on the level populations and line emission. Whether it does depends on the value of the cfrac parameter used in creating the populations files.

Parameters of photemis are almost identical to those of warmabs, except that instead of the column density, a normalization parameter rescales the line fluxes.

norm

The model supplies to xspec the emissivity of the gas, in units of \(\text{erg}\,\text{cm}^{-3}\,\text{s}^{-1}\), times a factor \(10^{10}\). So the physical meaning of the normalization \(\kappa\), is

\[\kappa=\frac{{\rm EM}}{4\pi D^2} \times 10^{-10}\]

where EM is the emission measure of the gas in the source (at the ionization parameter used in the fit) and \(D\) is the distance to the source.

multabs

Multabs tries to account for line broadening by absorption by multiple discrete components rather than by turbulence or bulk flow. This model is essentially identical to warmabs in that it uses the warm absorber spectrum generated by warmabs, but initially assuming that the lines are broadened only by thermal gas motions. It then replicates these lines a fixed number of times and spreads the components over a given velocity width. The input parameters include the same parameters as warmabs, column, ionization parameter, and elemental abundances. These control the properties of the individual absorbing components, in the same way as for warmabs. In addition, the user specifies the velocity spread of the components, still called vturb, and the covering fraction, cfrac. This covering fraction can be interpreted as a covering fraction in velocity space. The number of discrete components, \(n_\text{comp}\) is given by

\[n_\text{comp} = \texttt{cfrac}\times\frac{v_\text{turb}}{v_\text{therm}}~,\]

where \(v_\text{turb}\) is input by the user and \(v_\text{therm}\) is the thermal line width which is determined by the equilibrium temperature (calculated by xstar). The optical depth of each component is divided by the number of components, so that the total optical depth summed over the components is independent of their number. The number of components cannot be less than 1. If it is 1 then the component will be placed at the redshifted energy of the line. If it is greater than 1, then the components will be spaced uniformly in velocity from \(-v_\text{turb}\) to \(+v_\text{turb}\) relative to the rest energy of the line. There is no restriction on the value of cfrac, so it is possible to set cfrac to some large number and thereby fill a uniform trough in velocity with the line.

column: See warmabs.
rlogxi: See warmabs.
Cabund...Znabund: See warmabs.
write_outfile: See warmabs.
outfile_idx: See warmabs.
vturb: Velocity width the individual components are spread over. The components range from \(-v_\text{turb}\) to \(+v_\text{turb}\).
cfrac: Covering fraction in velocity space. Determines the number of velocity components.
Redshift: See warmabs.

hotabs

Hotabs is the coronal analog of warmabs. In this case the free parameter determining the ionization balance is the log of the temperature in units of \(10^4\,\text{K}\). All other parameters are the same as in warmabs.

column: See warmabs.
logt4: Log of the temperature in units of \(10^{4}\,\text{K}\), i.e. \(\texttt{logt4}=0\) corresponds to \(10^4\,\text{K}\) and \(\texttt{logt4}=3\) corresponds to \(10^7\,\text{K}\).
Cabund...Znabund: See warmabs.
write_outfile: See warmabs.
outfile_idx: See warmabs.
vturb: See warmabs.
Redshift: See warmabs.

hotemis

Hotemis is the coronal analog of photemis. In this case the free parameter determining the ionization balance is the log of the temperature in units of \(10^4\,\text{K}\). All other parameters are the same as in warmabs/photemis.

norm: See photemis.
logt4: Log of the temperature in units of \(10^{4}\,\text{K}\), i.e. \(\texttt{logt4}=0\) corresponds to \(10^4\,\text{K}\) and \(\texttt{logt4}=3\) corresponds to \(10^7\,\text{K}\).
Cabund...Znabund: See warmabs.
write_outfile: See warmabs.
outfile_idx: See warmabs.
vturb: See warmabs.
Redshift: See warmabs.

Creating Your Own Popoulation Files

All the models described in this chapter rely on pre-calculated files containing ion populations and line emissivities and opacities. The default distribution contains a set of these files but the user is strongly recommended to verify wether the default distribution files are appropriate for their use case (e.g., similar spectral energy distribution, density etc). We expect that the majority of users will need to recalculate population files specific for their science case.

The population files are calculated by running xstar with setup where the spatial zones cover a wide range of ionization parameters. SEE THREAD

Common block ‘ewout’

A feature added September 2007 is output of the strongest lines, sorted by element and ion into a common block called ‘ewout’ This feature is only available for the warmabs, photemis, hotemis, hotabs models (not windabs, or multabs). The contents of the common block are:

lmodtyp: identifies which model most recently put its output into the: common block. lmodtyp=1,2,3,4, where 1=hotabs, 2=hotemis, 3=warmabs, 4=photemis
newout: number of lines in the list. This is zeroed after each call: to warmabs, photemis, hotabs, etc.
lnewo: array conatining line indexes. These should correspod to the: line indexes in the ascii line lists on the xstar web page.

kdewo: character array containing the name of the ion

kdewol: character array containing the name of the lower level

kdewou: character array containing the name of the upper level

aijewo: array containing A values for the lines

flinewo: array containing f values for the lines

ggloewo: array containing statistical weights for the lower levels

ggupewo: array containing statistical weights for the upper levels

elewo: array containing the line wavelengths

tau0ewo: array containing the line center depths

tau02ewo:array containing the line depths at the energy bin nearest to line center

ewout: array containing line equivalent widths in eV, negative values correspond to emission

elout: array containing line luminosities in xstar units (erg/s/10^38)

The details of how to get at the contents of the common block are up to the user. Currently xspec does not have a mechanism to do this, but it is straightforward to write a small fortran code to call the models with suitable parameter values and print the common block from there. The calling sequence for an analytic model is described in the xspec manual. It is important to point out that the common block is overwritten at each call to one of the models, so it should be emptied by the calling program after each call to one of the models.

An example is as follows:

    program fphottst
 c
    implicit none
 c
    real ear(0:20000),photar(20000),photer(10000),param(30)
    integer ne,mm,ifl
    real emin,emax,dele
 c
    ne=10000
    emin=0.4
    emax=7.2
    dele=(emax/emin)**(1./float(ne-1))
    ear(0)=emin
    do mm=1,ne
      ear(mm)=ear(mm-1)*dele
      enddo
    write (6,*)ear(1),ear(ne),ear(ne/2)
    param(1)=2.
    param(2)=-4.
    param(13)=100.
    param(12)=0.
    param(3)=1.
    param(4)=1.
    param(5)=1.
    param(6)=1.
    param(7)=1.
    param(8)=1.
    param(9)=1.
    param(10)=1.
    param(11)=1.
    param(3)=0.
    call fhotabs(EAR,NE,PARAM,IFL,PHOTAR,PHOTER)
c
    call commonprint
c
    write (6,*)'after fwarmabs'
    do mm=1,ne
      write (6,*)ear(mm),photar(mm)/ear(mm)
      enddo
c
    stop
    end
    subroutine commonprint
c
    implicit none  !jg
c
    parameter (nnnl=200000)
c
    common /ewout/newout,lnewo(nnnl),kdewo(8,nnnl),
   $  kdewol(20,nnnl),kdewou(20,nnnl),aijewo(nnnl),flinewo(nnnl),
   $  ggloewo(nnnl),ggupewo(nnnl),
   $  elewo(nnnl),tau0ewo(nnnl),tau02ewo(nnnl),ewout(nnnl),
   $  elout(nnnl),lmodtyp
c
    real aijewo,flinewo,ggloewo,ggupewo,elewo,tau0ewo,tau02ewo,
   $  ewout,elout
    integer lnewo,newout,lmodtyp
    character*1 kdewo,kdewol,kdewou
    integer kk,mm   !jg
c
     if (lmodtyp.eq.1) write (6,*)'after hotabs',newout
     if (lmodtyp.eq.2) write (6,*)'after hotemis',newout
     if (lmodtyp.eq.3) write (6,*)'after warmabs',newout
     if (lmodtyp.eq.4) write (6,*)'after photemis',newout
     write (16,*)'index, ion, wave(A), tau0, tau0grid, ew (eV),',
   $ 'lum, lev\_low, lev\_up, a\_ij, f\_ij, g\_lo, g\_up'
      do kk=1,newout
       write (16,9955)kk,lnewo(kk),(kdewo(mm,kk),mm=1,8),
   $     elewo(kk),tau0ewo(kk),tau02ewo(kk),ewout(kk),
   $     elout(kk),
   $     (kdewol(mm,kk),mm=1,20),(kdewou(mm,kk),mm=1,20),
   $     aijewo(kk),flinewo(kk),ggloewo(kk),ggupewo(kk)
       enddo
9955   format (1x,2i8,1x,8a1,5(1pe11.3),1x,2(20a1,1x),4(1pe11.3))
c
    return
    end