Frequently Asked Questions

How can I use AtomDB 2.0.2 with my favorite analysis package?

To use the AtomDB 2.0.2 data you will need to set your analysis software up appropriately to access the data.

This page describes how to use the new data in the existing modeling codes. If your favourite suite is missing or you encounter any problems, please contact us.


To use the new data with XSPEC, you must set the APECROOT variable for the APEC/VAPEC model. To do this use the xset command:

xset APECROOT /path/to/atomdb/apec_v2.0.2

XSPEC v12.7.0 included the version 2.0.0 data of AtomDB by default, however bugs have been found in this and it should not be used.

Older versions of XSPEC were hard wired to assume that the AtomDB models (APEC, VAPEC) contain 14 elements, as was true in AtomDB 1.3.1. Therefore the XSPEC-friendly 14 element legacy version of AtomDB 2.0.2 has been produced, and this should be used with XSPEC versions older than 12.7.


As of version 4.3 (December 2010), the CIAO/Sherpa suite has the ability to change the variables passed to the XSPEC models (the “xset” commands). This can be used to change the version of the AtomDB database used when applying APEC models. A Sherpa FAQ thread has been created describing this here.

This will not work if you are using an older version of Sherpa, an upgrade to version 4.3 is required. Also, note that version 4.3 of Sherpa does not include version 12.7 of XSPEC, so the 'xspec_legacy' tarball should be used.

As of version 4.4 (December 2011), Sherpa includes the XSPEC 12.7 libraries, and is bundled with the full AtomDB v2.0.1. The full version of v2.0.2 can be installed using the xset commands.


ISIS relies on the ATOMDB environment variable to tell it the location of the version of the database that you wish to use. Before starting ISIS, type:

bash users: export ATOMDB=/path/to/atomdb
csh users: setenv ATOMDB "/path/to/atomdb"

It also uses the VERSION file within the AtomDB directory to know which files to obtain. The VERSION file contains the root of the filenames for the version, e.g. 2.0.2, 2.0.2_xspec, or 1.3.1 as appropriate. Make sure you have this correctly set (it should be correct, but if you unzipped both the XSPEC and full versions of AtomDB 2.0.2 into the same directory, it will point to whichever was opened last.)

Also, if using the XSPEC models within ISIS, you will again have to set the APECROOT variable using the xspec_xset command:

xspec_xset ("APECROOT", "/path/to/atomdb/atomdb_v2.0.2_xspec")

Note that ISIS can handle the full AtomDB, not just the xspec-friendly 14 elements, however if using the XSPEC models within ISIS you will have to revert to the 14 element version.

All of my abundances seem to be a bit messed up when using the 30 element AtomDB - what's going on?

There is a bug in XSPEC version 12.7.0, fixed in 12.7.0s, affecting the “wilm” abundances. If any of the abundances are zero in the loaded abundance set, XSPEC does not calculate the spectrum for that element. Due to the bug, this was not correctly indexed, leading to the incorrect element being removed. This only affects the wilm abundances, all others have small, finite values even for minor elements.

At the time of writing (Feb 10th 2012), Sherpa uses the 12.7.0 version of XSPEC, so using the wilm abundances should be avoided with any apec models.

How can I calculate the density in a plasma based on the XSPEC normalization?

After a fit using an APEC model, XSPEC returns a norm, which is simply the emission measure of the gas scaled by the distance,

\xi \equiv \int n_e n_H dV / (4 \pi D_A^2 (1+z)^2

where n_e, n_H are the electron and hydrogen densities and D_A is the angular diameter distance to the source (for a Galactic source, this is simply the normal distance). If the source is extragalactic, then the distinction is relevant, however. Using concordance cosmology values with the best-fit redshift z, D_A can be easily calculated. Then, however, some assumptions must be made about the volume and shape of the emitting plasma. Assuming the source is spherical, of uniform density, and fully ionized with 10\% He (implying n_e ~ 1.2 n_H), these equations can be rewritten as:

n_H = \sqrt{{(1+z)^2 \eta}\over{1.2 \theta^3 D_A }}

where theta is the angular size of the source.

What does it mean to call a collisional plasma model density-dependent?

All plasma emission models are inherently density-dependent, since the more dense the plasma, the more collisions will occur and the more emission will be generated. Since the collisions involve electrons and ions, the density-dependence due to this effect is proportional to the overall density squared. However, there is another type of density-dependence which occurs when some of the underlying assumptions for a coronal plasma break down. As the density increases, some metastable energy levels will tend to be excited (or de-excited) by collisions before sufficient time has elapsed for spontaneous radiative decay to occur. This will modify the emitted spectrum, increasing the strengths of some lines and decreasing others. The effect is subtle, and likely impossible to observe with low or moderate resolution detectors. However, high-resolution devices with E/dE > 300 will be able to detect such effects in hot plasmas.

What is the difference between NEI and CIE plasma models?

An "NEI" plasma is one with "non-equilibrium ionization", while a "CIE" plasma is in "collisional ionization equilibrium". Implied in the latter case is that the electron velocity distribution is described by the Maxwell-Boltzmann equation (i.e., it is a thermal plasma), and that the ion population for all atoms is not time-dependent (i.e, the rate of ionization out of any ion is exactly balanced by the rate of recombination. Simply because a plasma is in CIE does not mean that the entire system is in Local Thermodynamic Equilibrium (LTE); this occurs when each level of each ion is also in equilibrium, a much more restrictive statement that requires much higher densities than simple CIE (see the physics page for more details). An NEI plasma is simply defined as not being in CIE; it may not have a thermal distribution of electrons, or it may be undergoing more ionizations than recombinations (in which case it is often called an 'ionizing' plasma), or it may be undergoing more recombinations than ionizations (a so-called 'recombining' plasma). XSPEC contains a number of NEI models, all of which are actually models of 'ionizing' plasmas with some starting temperature (often assumed to be 10,000 K or possibly a fully-neutral gas) which is then assumed to have been shocked by being put into a plasma with some higher electron temperature. Such a plasma will eventually reach equilibrium at the new electron temperature; the speed of which is proportional to the electron density multiplied by the time.

How can I take into account errors in atomic models when fitting my models?

This is a difficult problem, unless you are willing to delve into the nuts and bolts of plasma modeling. Some researchers have used the approach of fitting their spectra using multiple models, such as the Mekal and APEC models available in XSPEC. However, this approach is not robust for the simple reason that many of the underlying calculations in both models come from the same source. For example, the hydrogen-like line emission in both codes relies on calculations done by D. Sampson and collaborators using a distorted-wave calculation that is known to be not as accurate as more recent R-matrix calculations. Therefore, good agreement between the two codes is often due to using the same inputs, rather than a true cross-check. This problem is being worked on by the ATOMDB team, but at the moment only preliminary results are available.

What is a Raymond-Smith plasma?

A "Raymond-Smith plasma" refers to the models described in Raymond & Smith (1977), which were created using the assumptions appropriate for a optically-thin thermal plasma in coronal equilibrium. Although the paper is justly famous, the better term for such a plasma is "optically-thin thermal plasma", since researchers in fields beyond X-ray astrophysics will then understand.

What is the difference between APEC, Mekal, and Raymond-Smith?

Please see the comparisons page for detailed comparisons between the difference codes. The codes themselves are all designed to perform similar calculations. The Raymond & Smith (1977) code, with the most recent (1993) update, is still available, although there is limited documentation (see the NEIline code for a better-documented front end). The code is still used in specific applications since it is extremely fast and can calculate CIE as well as NEI models. The Mekal code is so named because it was developed by Rolf Mewe and Jelle Kaastra. The final 'l' comes from Duane Liedahl who calculated the atomic parameters for a large number of iron L-shell ions. The code itself is not easily available, although it is included in XSPEC and could be extracted if desired. However, it is (like the Raymond & Smith code) no longer being updated. Finally, the APEC code (Astrophysical Plasma Emission Code) was developed by Randall Smith and Nancy Brickhouse. APEC uses the APED (Astrophysical Plasma Emission Database), which contains atomic rates and wavelengths to calculate the emission from an optically-thin thermal plasma, creating outputs which are combined with the APED to create the ATOMDB.

What is the NEIline code?

The NEIline code (available here) combines the Raymond-Smith code with a simple calling front-end that can be used to calculate line emission as a function of temperature, density, and ionization timescale. It is particularly useful when a line ratio must be calculated for an NEI model, although it can also be used to calculate line emissivities in equilibrium as well.

What is the 'NoLine' model?

The 'NoLine' model (details available here) is simply the standard output of APEC (two files, with names NoLine_line.fits and NoLine_coco.fits) where the continuum emission is normal, but the line emission has been completely removed. This is useful when a standard 'optically-thin thermal plasma' model is desired for the continuum, but the user plans to fit the emission lines using explicit Gaussians in order to calculate the line emission directly.