User Input to XSTAR

User Interface and Parameter Formats

For most applications, input parameters to XSTAR are parsed as command line arguments. If invoking XSTAR from the command line without further parameters, the user is prompted for a series of input values.

unix> xstar
  xstar version 2.59b
  covering fraction (0.:1.) [1.]
  temperature (/10**4K) (0.:1.e4) [400.]
  constant pressure switch (1=yes, 0=no) (0:1) [0]
  pressure (dyne/cm**2) (0.:1.) [0.03]
  density (cm**-3) (0.:1.e21) [1.e+4] 1.e8
  spectrum type?[pow]
  [...]

The format of each line is: description (min value : max value) [default value]. In this example we use default parameters, except for the density which we set to 1.0E+8.

Alternatively, parameter values can be specified directly on the command line.

unix> xstar cfrac=0 temperature=1000
  xstar version 2.59b
  constant pressure switch (1=yes, 0=no) (0:1) [0]
  pressure (dyne/cm**2) (0.:1.) [0.03]
  density (cm**-3) (0.:1.e21) [1.0e8]
  [...]

Now XSTAR only starts prompting at the constant pressure switch because covering fraction (cfrac) and temperature (temperature) are already defined. A complete list of parameters is given in Table Input Parameter Summary. Specifying all parameters will avoid prompting entirely and is particularly useful for scripting.

Internally, input parameters to XSTAR are handled through an IRAF-style interface, XPI, developed for the FTOOLS suite of programs. This interface expects a parameter file, a simple text file, called “xstar.par” at the location the user’s $PFILES environment variable points to. This environment variable is set upon initialization of HEAsoft and works similar to the PATH variable in that it may point to several locations (usually to $HOME/pfiles:$HEADAS/syspfiles). On the very first call of XSTAR, a local copy of a template parameter file is created from the system-wide default parameter file..

The parameter file contains information about which parameters exist and what their description, formats, limits and default values are. Upon inspection of the parameter file will users will note that the parameter file contains several more parameters than they get prompted. We refer to these as hidden parameters. Whether a parameter is hidden or prompted is an attribute defined in the parameter file itself. With only few exceptions, the hidden parameters are rather technical parameters that allow for controlling the code behavior at a very fundamental level. Changing these parameters requires a understanding of the operation of the code. Users should therefore use great caution when modifying hidden parameters.

Another feature the user may notice is that for some of the prompted parameters, the default values get updated when the parameter is changed. The updated values are stored in the user’s local copy of the parameter file. In order to undo all changes and start with a fresh set of default parameter, the user may simply delete the local copy of the parameter file which will lead XSTAR to revert to the system-wide default parameter file.

Obviously, the parameter file can also be used to save the complete setup of an XSTAR run for later reproducibility. However, there are certain caveats associated with this procedure. For example, the default values of hidden parameters have changed among different versions of XSTAR. Also for remote or large scale calculations, the user may want to avoid prompting completely, which also requires modifications to the parameter modes. The recommended way to save XSTAR calls is therefore in executable shell scripts that explicitly specify all prompted and other parameters of interest. For example, the following bash script will run XSTAR with default parameters without prompting.

#!/bin/bash
xstar cfrac=1.0 temperature=400 lcpres=0 pressure=0.03 \
density=1.e4 spectrum='pow' trad=-1. rlrad38=1.e-6 \
column=1.e17 rlogxi=5 abundtbl='xdef'

Input Parameter Summary

Here we list all XSTAR parameters in the order of the parameter file.

Input Parameter Summary
Prompt string	Parameter name	Description	Default
Temperature	`temperature`	Gas Temperature ($10^4\,\text{K}$ )	400
Pressure	`pressure`	Pressure in $\text{dynes}\,\text{cm}^{-2}$	0.03
Density	`density`	Density in $\text{cm}^{-3}$	1.0E+04
Spectrum	`spectrum`	Define the input spectrum	pow
Spectrum File	`spectrum_file`	Name of spectrum file	spct.dat
Spectrum Units	`spectun`	0=energy, 1=photons	0
Radiation Temperature or Alpha	`trad`	$10^7\,\text{K}$ or unitless ($E^{\alpha}$)	-1.0
Luminosity	`rlrad38`	Luminosity in $10^{38}\,\text{erg}\,\text{s}^{-1}$	1.0E-06
Column Density	`column`	Column density in $\text{cm}^{-2}$	1.0E+17
log(ionization parameter)	`rlogxi`	$\log(\xi)$ (erg cm/s) or $log(\Xi)$	5.0
Abundance table	`abundtbl`	Name of abundance table	xdef
(Hydrogen abundance)	`habund`	relative H abundance	1.0
(Helium abundance)	`heabund`	relative He abundance	1.0
(Lithium abundance)	`liabund`	relative Li abundance	0.0
(Beryllium abundance)	`beabund`	relative Be abundance	0.0
(Boron abundance)	`babund`	relative B abundance	0.0
(Carbon abundance)	`cabund`	relative C abundance	1.0
(Nitrogen abundance)	`nabund`	relative N abundance	1.0
(Oxygen abundance)	`oabund`	relative O abundance	1.0
(Fluorind abundance)	`fabund`	relative F abundance	1.0
(Neon abundance)	`neabund`	relative Ne abundance	1.0
(Magnesium abundance)	`mgabund`	relative Mg abundance	1.0
(Aluminum abundance)	`alabund`	relative Al abundance	1.0
(Silicon abundance)	`siabund`	relative Si abundance	1.0
(Phosphorus abundance)	`pabund`	relative P abundance	1.0
(Sulfur abundance)	`sabund`	relative S abundance	1.0
(Chlorine abundance)	`clabund`	relative Cl abundance	1.0
(Argon abundance)	`arabund`	relative Ar abundance	1.0
(Potassium abundance)	`kabund`	relative K abundance	1.0
(Scandium abundance)	`scabund`	relative Sc abundance	1.0
(Titanium abundance)	`tiabund`	relative Ti abundance	1.0
(Vanadium abundance)	`vabund`	relative V abundance	1.0
(Chromium abundance)	`crabund`	relative Cr abundance	1.0
(Manganese abundance)	`mnabund`	relative Mn abundance	1.0
(Iron abundance)	`feabund`	relative Fe abundance	1.0
(Cobalt abundance)	`coabund`	relative Co abundance	1.0
(Nickel abundance)	`niabund`	relative Ni abundance	1.0
(Zinc abundance)	`znabund`	relative Zn abundance	1.0
(Copper abundance)	`cuabund`	relative Cu Abundance	1.0
Model Name	`modelname`	Name used for this run	XSTAR Default
(Covering fraction)	`cfrac`	Covering Fraction	1.0
(Constant Pressure Switch)	`lcpres`	1=yes, 0=no	0
(nsteps)	`nsteps`	Number of steps	3
(niter)	`niter`	Number of iterations	0
(write switch)	`lwrite`	(1=yes, 0=no)	0
(print switch)	`lprint`	(1=yes, 0=no)	0
(emult)	`emult`	Courant multiplier	0.5
(taumax)	`taumax`	$\tau_\text{max}$ for courant step	5.0
(xeemin)	`xeemin`	minimum electron fraction	0.1
(critf)	`critf`	critical ion abundance	1.0E-07
(vturbi)	`vturbi`	turbulent velocity (km/s)	1.0
(radexp)	`radexp`	density distribution power law index	0.0
(ncn2)	`ncn2`	number of continuum bins	9999
(loopcontrol)	`loopcontrol`	loop control (0=standalone)	0
(npass)	`npass`	number of passes	1
(mode)	`mode`	Paramter Interface mode	ql

Detailed Description of XSTAR Parameters

Temperature (temperature)

Gas temperature in units of $10^4\,\text{K}$. It is important to note that in typical photoionization models, the temperature is not an independent parameter, but calculated by the code by calculating thermal equilibrium. XSTAR allows the user to specify whether thermal equilibrium is calculated or not via the niter parameter, which consequently affects the meaning of the temperature input parameter.

If the parameter niter is set to 0 then the input temperature is fixed at this value. This is be useful to calculate collision-dominated plasmas or to speed up calculations in general. Be aware that in this case the specified plasma is likely not int thermal equilibrium.

If the parameter niter is set to a non-zero value, the input temperature is used as a first guess in calculating the thermal equilibrium value.

Finally, this temperature is used to calculate the initial guess for the gas density, $n=P/(kT)$, for the constant pressure case.

The input format is a float. The default parameter value is 400.

Pressure (pressure)

Model pressure in $\text{dynes}\,\text{cm}^{-2}$. Note that this quantity represents the full isotropic pressure (neutral atoms + ions + electrons + trapped line radiation) instead of just the pressure due to hydrogen atoms and protons. Whether or not this quantity is held fixed is determined by the value of the constant pressure switch lcpres. If the pressure is constant then the appropriate definition of ionization parameter ($\Xi$) is adopted. In the constant density case, lcpres=0, then this quantity is ignored.

The input format is a float. The default value is 0.03.

Density (density)

Model gas density, $n$ in $\text{cm}^{-3}$. This is actually the hydrogen nucleus density, so that, e.g., the total particle density in a fully-ionized plasma with solar abundances is $2.3n$. Whether or not this quantity is held fixed is determined by the value of the constant pressure switch lcpres. If the density is constant then the appropriate definition of ionization parameter ($\xi$) is adopted. The default case is constant density. Optionally, the density can be made radius-dependent. See Radius Exponent (radexp) - hidden for details.

The input format is a float. The default value is 1.0E+04.

Spectrum (spectrum)

This parameter allows to define the incident spectral energy distribution. The user can select between powerlaw, black body, and bremsstrahlung models, or alternatively provide a tabulated spectrum. Note that numerical problems can arise if the radiation field is zero throughout a significant energy range, because then the photoionization rates for some ions may be zero, and these appear in the denominator of the equations for the ionization balance. The parameter format is a string. The following options exist:

Black body spectrum

Black body spectrum, defined as

\[A(\varepsilon) = \varepsilon^3 / (\exp(\varepsilon/kT)-1)\]

where $T$ is temperature in units of $10^7\,\text{K}$.

The black body spectrum is selected by spectrum=bbody.
Bremsstrahlung spectrum

Thermal bremsstrahlung spectrum, including gaunt factors, but not including $e-e$ bremsstrahlung. The input parameter for this model is plasma temperature in keV.

The bremsstrahlung spectrum is selected by spectrum=bremss.
Powerlaw spectrum

Simple photon power law, defined as

\[A(\varepsilon) = \varepsilon^{\alpha}\]

where $\alpha$ is the energy index of power law.

The user is cautioned that simple power laws can have unintended consequences owing to the fact that they are automatically extrapolated to the lowest (0.1 eV) and highest (1 MeV) energies employed in the calculation. This can cause processes such as stimulated recombination and Compton cooling to dominate the model results, and may not represent a physically realistic result. These effects can be avoided by the use of a simple file spectrum as demonstrated below.

The powerlaw spectrum is selected by spectrum=pow.
File spectrum

Fluxes and energies are read from a text file, with name given by the spectrum_file keyword. The format of the file is as follows: the first line must contain the integer number of (energy, flux) pairs; each of the the remaining lines contains one (energy, flux) pair, with energy in eV and flux in energy units. These values will be interpolated onto the energy grid used internally by XSTAR using logarithmic interpolation. Absolute fluxes are arbitrary as XSTAR will re-normalize the spectrum according to the specified luminosity. An example of a file which results in a $\varepsilon^{-1}$ spectrum power law spectrum between 0.1 Ry and 1000 Ry (and zero elsewhere) is as follows:
```
006
1.0000E-03 1.E-10
1.3590E+00 1.E-10
1.3598E+00 1.E+11
1.3598E+05 1.E+06
1.3600E+05 1.E-10
2.0000E+05 1.E-10
```
As already states, be aware that small numbers (less than 1.E-30, say), may result in undesired results owing to the limitations of many machines in the range of exponents. And remember that it is not necessary to use actual physical units in specifying the input spectrum (except to distinguish between photon and energy fluxes) since the entire spectrum is re-normalized to conform to the luminosity specified.

The file spectrum is selected by spectrum=file.

The input format is a string. The default parameter value is “pow” (powerlaw).

Spectrum File (spectrum_file)

If the “file” option is chosen for the spectrum type, the user must provide a text file of the spectrum in the current working directory. The first line of the text file must be the number of energies listed in the table. The remaining lines are the energy channel (in eV) and the flux in units of $\text{photons}\,\text{cm}^{-2}\,\text{s}^{-1}\,\text{erg}^{-1}$ or $\text{erg}\,\text{cm}^{-2}\,\text{s}^{-1}\,\text{erg}^{-1}$ (see Spectrum Units (spectun)). Again, remember that it is not necessary to use actual physical units in specifying the input spectrum (except to distinguish between photon and energy fluxes) since the entire spectrum is re-normalized to conform to the luminosity specified.

The input format is string. The default parameter value is “spct.dat”.

Spectrum Units (spectun)

The appropriate units for the spectrum file specified above (1 = $\text{photons}\,\text{cm}^{-2}\,\text{s}^{-1}\,\text{erg}^{-1}$, 0 = $\text{erg}\,\text{cm}^{-2}\,\text{s}^{-1}\,\text{erg}^{-1}$).

New in version 221bn18 is a feature which allows reading in of table spectra in units of $\log10(\text{F}_\varepsilon)$, where $\text{F}_\varepsilon$ has units $\text{erg}\,\text{cm}^{-2}\,\text{s}^{-1}\,\text{erg}^{-1}$. This requires that the spectun input parameter be set to 2.

The input format is an integer. The default parameter value is 0 (energy flux)

Radiation Temperature or Alpha (trad)

This parameter pulls double duty, used to enter the radiation temperature in units of $10^7\,\text{K}$ in the case of a blackbody or in units of $\text{keV}$ for bremsstrahlung input model. It also is used to input the power-law index (in energy), $\alpha$, in the case of a power-law model. Note that $\alpha$ is defined as in $L_\varepsilon\sim\varepsilon^{\alpha}$ so generally $\alpha$ will be less than zero (this is the opposite of the convention used by xspec). XSTAR always works with specific luminosity $L_\varepsilon$ in units $\text{erg}\,\text{s}^{-1}\,\text{erg}^{-1}$, and never uses $\varepsilon L_\varepsilon$ or $\nu F_\nu$, for example.

The input format is a float. The default parameter value is -1.

Luminosity (luminosity)

Model luminosity integrated between 1 and 1000 Ry in units of $10^{38}\,\text{erg}\,\text{s}^{-1}$. In combination with the ionization parameter and the density, this parameter determines the geometrical size of the cloud.

The input format is a float. The default parameter value is 1.0E-06.

Column density (column)

Model column density, $N$ in units of $\text{cm}^{-2}$. This quantity is used in calculation of the thickness of the model slab according to

\[N=\int_{R_\text{in}}^{R_{out}} n\,dr~,\]

where $n$ is the density or an estimate based on pressure and temperature initial values. The model calculation terminates when this value is reached. For the constant density case, the calculation of the slab thickness simplifies to $R_\text{max}=N/n$.

The input format is a float. The default parameter value is 1.0E+21.

Log of the ionization parameter (rlogxi)

Initial value of the log (base 10) of the model ionization parameter at the innermost shell. If the density is held constant, the Tarter et al. [187] form is used:

\[\xi = \frac{L}{nR^2}~.\]

If the pressure is held constant, a version of the Krolik et al. [126] form is used:

\[\Xi = \frac{L}{4\pi c R^2 P}~.\]

Note that this differs from the original form by using the full isotropic pressure (neutral atoms + ions + electrons + trapped line radiation) instead of just the pressure due to hydrogen atoms and protons. This quantity is used in calculating the radius of the innermost edge of the shell by inverting the parameter definition.

The input format is a float. The default parameter value is 5.

Abundances

Atomic abundances for elements H though Zn are entered as a predefined abundance table. Additionally the user can change the value of each element relative to this table. For abundance tables, the user can select between XSTAR default abundances (close to those defined in Grevesse et al. [101]) and all abundance tables implemented in xspec. The abundance table is specified as a 4 character string for the parameter abundtbl. The full list of tables is

xdef (xstar default)
angr (Anders and Grevesse [21])
aspl (Asplund et al. [23])
feld (Feldman [87])
aneb (Anders and Ebihara [20])
grsa (Grevesse and Sauval [102])
wilm (Wilms et al. [194])
lodd (Lodders [134])
lpgp (Lodders et al. [133])
lpgs (Lodders et al. [133])

All abundance tables listed below. The default parameter is “xdef”.

Abundance Tables
Z	El	xdef	angr	aspl	feld	aneb
1	H	1.00E+00	1.00E+00	1.00E+00	1.00E+00	1.00E+00
2	He	1.00E-01	9.77E-02	8.51E-02	9.77E-02	8.01E-02
3	Li	1.00E-10	1.45E-11	1.12E-11	1.26E-11	2.19E-09
4	Be	1.00E-10	1.41E-11	2.40E-11	2.51E-11	2.87E-11
5	B	1.00E-10	3.98E-10	5.01E-10	3.55E-10	8.82E-10
6	C	3.70E-04	3.63E-04	2.69E-04	3.98E-04	4.45E-04
7	N	1.10E-04	1.12E-04	6.76E-05	1.00E-04	9.12E-05
8	O	6.80E-04	8.51E-04	4.90E-04	8.51E-04	7.39E-04
9	F	3.98E-08	3.63E-08	3.63E-08	3.63E-08	3.10E-08
10	Ne	2.80E-05	1.23E-04	8.51E-05	1.29E-04	1.38E-04
11	Na	1.78E-06	2.14E-06	1.74E-06	2.14E-06	2.10E-06
12	Mg	3.50E-05	3.80E-05	3.98E-05	3.80E-05	3.95E-05
13	Al	2.45E-06	2.95E-06	2.82E-06	2.95E-06	3.12E-06
14	Si	3.50E-05	3.55E-05	3.24E-05	3.55E-05	3.68E-05
15	P	3.31E-07	2.82E-07	2.57E-07	2.82E-07	3.82E-07
16	S	1.60E-05	1.62E-05	1.32E-05	1.62E-05	1.89E-05
17	Cl	3.98E-07	3.16E-07	3.16E-07	3.16E-07	1.93E-07
18	Ar	4.50E-06	3.63E-06	2.51E-06	4.47E-06	3.82E-06
19	K	8.91E-08	1.32E-07	1.07E-07	1.32E-07	1.39E-07
20	Ca	2.10E-06	2.29E-06	2.19E-06	2.29E-06	2.25E-06
21	Sc	1.66E-09	1.26E-09	1.41E-09	1.48E-09	1.24E-09
22	Ti	1.35E-07	9.77E-08	8.91E-08	1.05E-07	8.82E-08
23	V	2.51E-08	1.00E-08	8.51E-09	1.00E-08	1.08E-08
24	Cr	7.08E-07	4.68E-07	4.37E-07	4.68E-07	4.93E-07
25	Mn	2.51E-07	2.45E-07	2.69E-07	2.45E-07	3.50E-07
26	Fe	2.50E-05	4.68E-05	3.16E-05	3.24E-05	3.31E-05
27	Co	1.26E-07	8.32E-08	9.77E-08	8.32E-08	8.27E-08
28	Ni	2.00E-06	1.78E-06	1.66E-06	1.78E-06	1.81E-06
29	Cu	3.16E-08	1.62E-08	1.55E-08	1.62E-08	1.89E-08
30	Zn	1.58E-08	3.98E-08	3.63E-08	3.98E-08	4.63E-08

Abundance Tables
Z	El	grsa	wilm	lodd	lpgp	lpgs
1	H	1.00E+00	1.00E+00	1.00E+00	1.00E+00	1.00E+00
2	He	8.51E-02	9.77E-02	7.92E-02	8.41E-02	9.69E-02
3	Li	1.26E-11	0.00E+00	1.90E-09	1.26E-11	2.15E-09
4	Be	2.51E-11	0.00E+00	2.57E-11	2.40E-11	2.36E-11
5	B	3.55E-10	0.00E+00	6.03E-10	5.01E-10	7.26E-10
6	C	3.31E-04	2.40E-04	2.45E-04	2.45E-04	2.78E-04
7	N	8.32E-05	7.59E-05	6.76E-05	7.24E-05	8.19E-05
8	O	6.76E-04	4.90E-04	4.90E-04	5.37E-04	6.06E-04
9	F	3.63E-08	0.00E+00	2.88E-08	3.63E-08	3.10E-08
10	Ne	1.20E-04	8.71E-05	7.41E-05	1.12E-04	1.27E-04
11	Na	2.14E-06	1.45E-06	1.99E-06	2.00E-06	2.23E-06
12	Mg	3.80E-05	2.51E-05	3.55E-05	3.47E-05	3.98E-05
13	Al	2.95E-06	2.14E-06	2.88E-06	2.95E-06	3.27E-06
14	Si	3.55E-05	1.86E-05	3.47E-05	3.31E-05	3.86E-05
15	P	2.82E-07	2.63E-07	2.88E-07	2.88E-07	3.20E-07
16	S	2.14E-05	1.23E-05	1.55E-05	1.38E-05	1.63E-05
17	Cl	3.16E-07	1.32E-07	1.82E-07	3.16E-07	2.00E-07
18	Ar	2.51E-06	2.57E-06	3.55E-06	3.16E-06	3.58E-06
19	K	1.32E-07	0.00E+00	1.29E-07	1.32E-07	1.45E-07
20	Ca	2.29E-06	1.58E-06	2.19E-06	2.14E-06	2.33E-06
21	Sc	1.48E-09	0.00E+00	1.17E-09	1.26E-09	1.33E-09
22	Ti	1.05E-07	6.46E-08	8.32E-08	7.94E-08	9.54E-08
23	V	1.00E-08	0.00E+00	1.00E-08	1.00E-08	1.11E-08
24	Cr	4.68E-07	3.24E-07	4.47E-07	4.37E-07	5.06E-07
25	Mn	2.45E-07	2.19E-07	3.16E-07	2.34E-07	3.56E-07
26	Fe	3.16E-05	2.69E-05	2.95E-05	2.82E-05	3.27E-05
27	Co	8.32E-08	8.32E-08	8.13E-08	8.32E-08	9.07E-08
28	Ni	1.78E-06	1.12E-06	1.66E-06	1.70E-06	1.89E-06
29	Cu	1.62E-08	0.00E+00	1.82E-08	1.62E-08	2.09E-08
30	Zn	3.98E-08	0.00E+00	4.27E-08	4.17E-08	5.02E-08

In addition to specifying the abundance table, the user can also change the abundance of individual elements, relative to that table. This is particularly important for turning off individual elements. The relative element abundance parameters are habund, heabund, liabund, …, niabund, cuabund, and znabund.

Note that the abundance of an element relative to hydrogen depends both on the abundance table and the relative abundance parameter.

The input format for the abundance table is a string. The default is “xdef”.

The input format for the relative abundances are floats. The default values are 1.0 for all elements except for Li, Be, and B, which are 0.

Model Name (modelname)

Model name as 80 character string. The model name is recorded in all output files but does not affect the XSTAR run in any other way.

The input format is a string. The default parameter value “XSTAR Default”.

Covering Fraction (cfrac) - hidden

This parameter determines whether the geometry is a complete sphere or covers only part of the continuum source. In the former case, photons escaping the cloud in the ‘inward’ direction are assumed to reenter the cloud at the inner edge owing to the assumption of spherical symmetry. Default is 1.0.

cfrac is solely for deciding how the escape probabilities and optical depths are calculated. It is designed to distinguish between a plane-parallel slab where both the reflected and transmitted light is of interest (or a spherical shell with many holes so that both inward and outward light escape), vs. a closed sphere in which the only radiation which is observed is emitted outward. This is illustrated below.

_images/cfrac-01.png — Schematic illustration of the covering fraction parameter in XSTAR. For `cfrac=1` (top) all escaping inward radiation is assumed to re-enter the absorber due to spherical symmetry. No inward radiation leaves the cloud. For `cfrac=0` all radiation in inward direction that leaves the cloud is observed. This is would often be interpreted as reflection off a slab. The escaping radiation in outward direction is only mildly affected due to the internal radiation field. In particular it is *not* down-scaled by the value of `cfrac` nor diluted by unabsorbed, incident radiation.

The covering fraction does not directly affect how much total line radiation is emitted, so it is counter-intuitive in that sense. Hence it is not expected that, for example, cfrac=0.5 would produce half as much line luminosity seen by a distant observer as cfrac=1. This interpretation is also different from most of the observational astrophysical literature where covering fraction usually refers to a mixing of unabsorbed and transmitted radiation. The XSTAR output separates inward and outward emitted, as well as incident and transmitted radiation so that such models can be easily constructed by the user.

In XSTAR, cfrac affects the composition of the radiation field inside the absorber. Here is how it works: XSTAR divides the radiation field into two components: inward or reflected, and outward or transmitted. At each point in the model it needs to know the escape probabilities in each of these directions in order to calculate how much of the locally emitted line radiation will escape to a distant observer, in either direction. As XSTAR progresses through the cloud it calculates the opacities and optical depth of the material at each radius. Thus at a given radius it knows accurately the optical depth, and hence the escape probability, in the inward or reflected direction. It does not know the optical depth in the outward direction, at least at first, because it has not calculated the ionization, temperature and opacity there yet. So it guesses at first, and assumes the optical depths are zero, and so the escape probability is 1. If you do a multi-pass model then it will use the optical depths from an earlier pass for the outward optical depth, and so it will be self-consistent. If cfrac=0 xstar follows this procedure and provides the total escaping luminosities of all the lines and rrcs in the inward and outward directions.

If cfrac=1 then xstar uses an assumption which originates from early historical photoionization models: it assumes that there is no inward or reflected radiation, and that all radiation is emitted in the outward direction. This is motivated by the assumption that the cloud is spherical, and that a sort of “Gauss’s law” holds: any light emitted inward at a given radius will traverse the spherical region interior to that without interacting, and emerge at the same radius, and then have to traverse the same gas at larger radii as it would have if it were initially emitted outward. It also makes another major assumption: that the optical depth traversed in the outward direction is the same as the optical depth in the inward direction, which of course has already been calculated at a given radius as xstar proceeds outward in radius. So, if cfrac=1, there is no radiation escaping in the inward direction. If cfrac is between 0 and 1 then xstar does a linear interpolation between the two limits.

New in version 2.54a is the inclusion of radiative excitation. This process is discussed in more detail in section 9.D.2. The rate of radiative excitation of a given transition is calculated as described there, and then multiplied by a factor of 1-cfrac. So, if cfrac=1 the effective rate of radiative excitation is zero. If cfrac=0 then the full rate of radiative excitation is included.

The input format is a float. The default parameter value is 1.0.

Constant Pressure Switch (lcpres) - hidden

This parameter chooses between constant density (lcpres= 0) and constant pressure (lcpres=1). This switch also affects the definition of the ionization parameter ($\Xi$ or $\xi$)

The input format is an integer. The default is value is 0 (constant density).

Number of Steps (nsteps) - hidden

This parameter controls the maximum number of spatial zones used in a calculation, only in the case where the Courant condition step is larger than the size of the slab. That is, the step size is calculated as:

\[\Delta R = min( {\rm emult}/\kappa_{max}(\varepsilon), R/{\rm nsteps})\]

where emult is defined below, and $\kappa_{max}(\varepsilon)$ is the maximum opacity from the previous step calculation. $\kappa_{max}(\varepsilon)$ is only calculated from energies where the optical depth to the illuminated face of the cloud is less than taumax, where taumax is defined below.

The input format is an integer. The default parameter value is 2.

write switch (lwrite) - hidden

If the argument is a non-zero integer, level populations and line emissivities in the interior of the shell will be written to a FITS dataset at each spatial step for later examination or plotting. These files are named ‘xo0n_detail.fits’ … ‘xo0n_detal4.fits’, where n is the pass number. These can become quite large (hundreds of MB to several GB) for a model with many spatial zones. Various FITS file manipulation routines can be used to filter and plot the quantities in these files.

New in version 2.5: if this parameter has a value -1 no fits output is produced.

The input format is an integer. The default parameter value is 0.

print switch (lprint) - hidden

This parameter enables the printing of many quantities which are defined locally at the last spatial zone of the calculation. These include ion fractions, heating and cooling rates, line and continuum emissivities and opacitites, execution times, and level populations. They are printed to the log file “xout_step.log”.

lprint=0 results in just the 500 brightest line luminosities (sorted by luminosity) and depths, and the 500 brightest recombination continuum (sorted by luminosity) luminosities and depths to be printed to the log file at the end of the run.

lprint=1 causes many additional quantities to be printed, including ASCII tables of total line and RRC luminosities and depths.

lprint=2 additionally prints many useful local quantities such as ion fractions, thermal rates, level populations. Note that these local quantities are printed only at the final step of the model run.

lprint=3 prints continuum luminosities and emissivities.

lprint=4 the list of lines is printed, along with upper and lower levels, transition probabilities and statistical weights.

lprint=5 prints all rates affecting level populations, ionization, heating and cooling internal to the code. Interpreting these require familiarity with the internal operation of the code.

This switch affects only the ASCII log file, xout_step.log. The standard FITS output files are unaffected by the value of lprint.

A feature added in version 2.5: if this parameter is given a value -1 only a very minimal printout is given after the final spatial zone: just the position, ionization parameter, heating and cooling rates. This option is designed to provide a streamlined printout in the case of a very large xstar2xspec run.

The input format is an integer. The default parameter value is 0.

Courant Multiplier (emult) - hidden

This is a constant factor used in calculating the spatial step size. For each radial zone, the size of the next zone is chosen to be

\[\Delta R = min( {\rm emult}/\kappa_{max}(\varepsilon), R/{\rm nsteps})\]

where emult is defined below, and $\kappa_{max}(\varepsilon)$ is the maximum opacity from the previous step calculation. $\kappa_{max}(\varepsilon)$ is only calculated from energies where the optical depth to the illuminated face of the cloud is less than taumax, where taumax is defined below. Values outside the range 0.1–1 are unlikely to be of any practical value.

The input format is a float. The default parameter value is 0.5.

Max Tau for Courant Step (taumax) - hidden

This quantity is used in calculating the spatial step size, as described in the previous subsection. Energy bins with continuum optical depth to the illuminated cloud face greater than taumax are not used when searching for the maximum photoelectric opacity.

The parameter format is a float. The default parameter value is 5.

Min Electron Abundance (xeemin) - hidden

This is the minimum allowed electron fractional abundance. If the electron fraction falls below this value the current pass is ended.

The input format is a float. The default paramter value is 0.1.

Critical Ion Fraction (critf) - hidden

Ions whose abundance relative to total hydrogen (H I + H II) are less than this value after the preliminary ion abundance calculation (See Chapter~ref{sec:internals}) are not included in full multilevel calculation. This parameter should be changed with caution owing to the fact that it determines the size of the matrix that xstar tries to solve in calculating the level populations.

In versions of xstar 2.1lxx and earlier this matrix had a maximum size of 2400, and an attempt to solve for more than this number of levels simultaneously would result in xstar stopping with a message “ipmat too large”.

In version 2.2 and later this limitation has been removed, and arbitrarily small values of critf can be accomodated. Also, a faster algorithm has been adopted for the multi-level calculation, so the speed advantages of large critf have been reduced. Also, the input parameter critf now refers to the fractional ion abundance (i.e. relative to the parent element) rather than the absolute (i.e. relative to H) ion abundance.

The input format is a float. The default parameter value is 1.0E-07.

Turbulent Velocity (vturbi) -hidden

This parameter is the turbulent velocity in units of $\text{km}\,\text{s}^{-1}$ and allows extra line broadening to be introduced into the calculation of the synthetic spectrum. This quantity enters into the calculation of the line profile function, which is used by the line opacity and emissivity. The line profile function is a Voigt profile, which resembles a Gaussian in the Doppler core. The turbulent velocity then enters into the “sigma” of the Gaussian. The Gaussian “sigma” in velocity units is $(v_\text{turb}^2+v_\text{therm}^2)^{1/2}$ where $v_\text{therm}$ is the ion thermal speed.

The input format is a float. The default parameter value is 1.0.

Number of Passes (npass) - hidden

This parameter determines how many complete calculations of the temperature and ionization structure of the model shell are made. Multiple passes are needed because there is no a priori knowledge of the optical depth of the shell in all the lines and continua, and these can affect the state of the gas in the interior of the shell. During the first pass the calculation proceeds through the shell, and assumes that all optical depths from points within the shell to the far edge of the shell are 0. If an integer greater than 1 is supplied as a parameter, XSTAR performs that number of iterations through the entire calculation, setting the optical depths to the far edge at the values calculated in the previous iteration. The odd numbered passes are made from the smallest to largest radius, while the even numbered passes are made in the inward direction. The emergent spectrum is not calculated accurately during the inward passes, so npass must be odd. Multi-pass calculations substantially improve the accuracy of the predictions made for shells with finite thickness, but they are much more time consuming than single-pass calculations. They also make use of temporary unformatted datasets, named ‘xout_tmp.lis’, ‘xout_tmp2.lis’, which can become quite large.

The input format is an integer. The default parameter value is 1.

Number of Iterations (niter) - hidden

Set maximum number of iterations for thermal equilibrium and charge neutrality calculation at each spatial step. If this quantity is set to zero then a constant temperature run will result, and charge neutrality will not be calculated. If this quantity is negative, then charge neutrality will be calculated, but thermal equilibrium will not. Normal thermal equilibrium models can be calculated with niter=99, although the code seldom requires more than a few iterations (10 or 20 at most) to achieve thermal equilibrium under normal conditions. If niter=0 then the assumed value for the electron fraction relative to total hydrogen is 1.0.

The input format is an integer. The default parameter value is 0 (neither thermal equilibrium nor charge neutrality).

Radius Exponent (radexp) - hidden

New in version 2.2 is the ability to have the gas density variable as a power law in radius, i.e. $n=n_0(R/R_0)^\text{radexp}$, where $n_0$ and $R_0$ are the density and radius at the cloud illuminated face. Note that this creates the possibility for calculations which do not end. This because the criteria for a model to end are either that the input column density is reached, or that the electron fraction falls below xeemin. If radexp has a value $\leq -1$ then the column density integral converges only logarithmically at best, and the specified column may never be reached. If radexp $\leq -2$ the local ionization parameter will increase with radius, and so the gas will not recombine and the xeemin criterion will not be met.

New in version 221bn17 is a feature which allows an array of densities to be read in. It requires that the radexp input variable be set to a number more negative than $-100$. Then ordered pairs of (radius, density) are read in from a file called ‘density.dat’. Reading continues until the end of the file is reached. The density and radius values override the values derived from the ordinary input parameters. But execution will stop if other ending criteria are satisfied, i.e. if the model column density exceeds the input value, or the electron fraction falls below the specified minimum. The code will stop with an error if the density.dat file does not exist, or if the radius values are not monotonically increasing.

The input format is a float. The default parameter value is 0.0 (constant density).

Number of Continuum bins (ncn2) - hidden

New in version 2.2 is the option to control the number of continuum bins. Continuum bins are logarithmically spaced between 0.1 eV and 40 keV, and are calculated according to:

\[\Delta\varepsilon/\varepsilon=(40 {\rm keV}/0.1 {\rm eV})^{1/(0.49 {\rm ncn2})}\]

ncn2 must be in the range between 999 and 999999. The higher value is appropriate for use in modeling X-ray grating spectra. The lower value is appropriate for models where only integrated line luminosities or ionization fractions are desired. Execution time scales approximately proportionately to ncn2.

The input format is an integer. The default parameter is 9999.

Loop Control (loopcontrol) - hidden

Used by XSTAR2XSPEC to track each model generated. This value should never be manipulated by the end user.

The input format is an integer. The default parameter value is 1.

mode - hidden

This parameter is used by the XPI interface and determins the behavior of the parameter input by the user, for example whether user parameters should be saved for the next call of XSTAR or whether XSTAR should start again from default parameters. This value should never be manipulated by the end user.

The input format is a string. The default parameter value is “ql” (query and learn).