Problems and Pitfalls

XSTAR has been designed to be as “user-friendly” as possible while still maintaining a large amount of flexibility. However, experience has shown that it is difficult to guard against the many possible misuses of the code, and that it is impossible to generate a code which is completely free from errors or unintended features. In this chapter we list what we consider to be some of the most probable pitfalls of the use of XSTAR. This chapter should be read by any user who runs XSTAR2XSPEC or who ventures very far beyond the default parameter values of XSTAR itself.

Mtables

If you are using \(\texttt{mtables}\) with variable abundances, then you will likely get totally unphysical results. See Variable Abundances in Table Models for details.

Execution Time

XSTAR is designed to strike a balance between accuracy and speed, but this inevitably involves some disparity between different computing platforms. As a result, many problems of interest require large amounts of time on machines which are relatively slow, or which are heavily used for other tasks.

In an effort to avoid wasted time (and CPU cycles) we offer the following suggestions: (i) XSTAR does not attempt to calculate ionization, excitation, etc. for elements whose abundances are specified to be less than \(10^{-15}\) relative to hydrogen. Large reductions in computation time can be achieved by zeroing the abundances of elements which are likely to be unimportant anyway, for example, calcium, argon, and nickel. (ii) For some purposes constant temperature is an adequate approximation, and is often a useful preliminary step in deciding parameter values such as column density, and require a fraction of the execution time of full thermal equilibrium models. (iii) For some purposes a low column density (\(\leq 10^{18}\,\text{cm}^{-2}\)) will provide sufficient information. Large column densities require significantly more execution time. If large columns are needed, then execution can be speeded up by use of a large value of emult, or a small value of taumax, and by setting npass to 1. (iv) Reduce the number of continuum bins on input. Execution time is approximately proportional to the number of continuum bins.

The parameter files included in the source tree for both xstar and xstar2xspec are set to perform constant temperature models, in order to allow the user to become familiar with xstar without requiring large investments in computer time.

Low Density

Although all rates should extrapolate correctly at low density, the level population calculation requires the inversion of large matrices of rates. In most cases, the largest elements of the matrix are the spontaneous decay rates (A values) for allowed transitions. For highly charged ions these can exceed \(10^{13}\,\text{s}^{-1}\). At low densities the smallest rates of interest are the collisional rates and recombination rates. XSTAR attempts to avoid inverting singular matrices by discarding rows and columns whose largest elements differ from the largest element in the matrix by more than the machine precision (and then assuming the populations in the associated levels are zero). This can have the effect of producing inaccurate solutions particularly at low densities since some physically important transitions (notably recombination) may be discarded. Unfortunately, there is no clear way of automatically informing the user when this is happening. A rough rule of thumb is that densities less than approximately 1000 should be avoided when iron may be ionized beyond Fe XVII.

An indication of possible numerical problems is given by the final integer on each line of the output log file. This is the number of iterations required in order to reach thermal equilibrium and charge neutrality. Models with good convergence will typically have values of 5 or less for this quantity, except for the first step and possibly near ionization fronts. Otherwise, if this integer is large (i.e. greater than, say, 20), and if the value of heating - cooling (“h-c”) is greater than \(1\text{--}2\%\), then it is possible that the density is lower than can be treated accurately by XSTAR.

High Density

All level populations are affected by collision rates to and from the superlevels. These rates are calculated by fitting to more complete population kinetic calculations involving hundreds of levels; these fits are valid only up to (electron) densities of \(10^{22}\,\text{cm}^{-3}\). However, for densities greater than \(10^{18}\,\text{cm}^{-3}\) special atomic data files should be used. Please contact us in this case.

The Energy Grid

Many of the most important components of the XSTAR calculation require numerical quadratures over energy, and these are generally carried out using straight-forward trapezoid quadratures over a fixed grid of energies. In addition, the computation is speeded by the use of a strictly logarithmic grid spacing in energy. We use 9999 energies spaced logarithmically from 0.1 eV to 20 keV. This results in a \(0.12\%\) grid spacing, corresponding to, e.g. 8.6 eV at 7 keV. This is the energy resolution of the code. Finer resolution can be implemented if larger values of ncn2 are used, up to a limit of ncn2=999999.

The Ionizing Spectrum

The ionizing spectrum has the obvious effect of creating ionization in the gas. But it also can influence the heating and cooling via Compton scattering if the gas is highly ionized. The standard ionizing spectrum options apply to all the energies in the grid. Therefore if, for example, an \(\varepsilon^{-1}\) power law is chosen the temperature in Compton equilibrium will be \(kT=(\varepsilon_{max}-\varepsilon_{min}) /(4 {\rm ln}(\varepsilon_{max}/\varepsilon_{min}))\), and power law indeces which are greater (or less) than 1 will be influenced even more strongly by the choice of minimum (or maximum) energy. It is likely that the default choice we have made will not be the choice which is physically appropriate for the situation of interest, so the user is encouraged to input the spectral model from a file, with the appropriate cutoffs built in, in situations where power law spectra and Compton heating/cooling are important.

Energy Budget

In models where thermal equilibrium is imposed the total amount of energy absorbed from the incident radiation field should balance the total emitted energy in lines and continua. This constraint is not automatically satisfied, since the algorithm for calculating heating and cooling rates is based on the assumption that each spatial zone is at most marginally optically thick. As a check the total energy absorbed and emitted from the radiation field is printed at the end of the log file, along with the fractional error in energy conservation. An error greater than a few percent indicates an inaccuracy in the model results which may significantly compromise emission line strengths, for example. Such models should propbably be rerun with smaller values of emult.