.. SPDX-FileCopyrightText: 1992-2026 NWO-I/SRON Space Research Organisation Netherlands
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _sect:apec:

APEC: collisional ionisation equilibrium model (External)
=========================================================

This model calculates the spectrum of a plasma in collisional ionisation
equilibrium (CIE), based on the APEC table model from ATOMDB. 
Despite of the similarity between this model and the XSPEC implementation,
the underlying algorithm to interpolate the APEC table model is unlikely to be identical.
This design allows direct comparison between SPEX CIE and XSPEC APEC implementations, 
providing insight into the systematic uncertainties introduced by interpolation.

The SPEX evaluation of APEC may differ slightly from the XSPEC implementation
due to differences in the interpolation algorithms. In addition, the
normalization follows the SPEX convention. This means that a SPEX-APEC model,
at its default distance and with a normalization of :math:`4\pi`, corresponds
to an XSPEC-APEC model evaluated at zero redshift.

.. note:: The current apec model cannot be used to read the APEC-NEI fits table.

Install
-------

Before the APEC model in SPEX can be used, ATOMDB should be installed 
on your machine. If you do not have an ATOMDB installation yet, please 
`download ATOMDB here <http://www.atomdb.org/download.php>`_. 

Before loading SPEX, please make sure to set the ``APECROOT`` environment
variable to the location of your ATOMDB installation, more specifically
the path to the ``apec_coco.fits`` and ``apec_line.fits`` files. For example::

    export APECROOT=/home/user/atomdb/atomdb_v3.1.2
    
or in C-type shells::

    setenv APECROOT /home/user/atomdb/atomdb_v3.1.2

When the variable is set correctly, SPEX can find the table models automatically.


Abundances
----------

The SPEX implemenatation of APEC does use the SPEX abundance setting.
Please take care to set the abundance to a similar set if you want to
compare APEC with the original XSPEC implementation.  


Parameter description
---------------------

The parameters of the model are:

| ``norm`` : the normalisation, which is the emission measure
  :math:`Y \equiv n_{\mathrm H} n_{\mathrm e} V` in units of
  :math:`10^{64}` :math:`\mathrm{m}^{-3}`, where
  :math:`n_{\mathrm e}` and :math:`n_{\mathrm H}` are the electron and
  Hydrogen densities and :math:`V` the volume of the source. 
  At the default SPEX distance and with a normalization of :math:`4\pi`, 
  this model corresponds to an XSPEC-APEC model evaluated at zero redshift.
  Default value: 1.
| ``t`` : the electron temperature :math:`T_{\mathrm e}` in keV. Default
  value: 1.
| ``vrms`` : RMS Velocity broadening in km/s (see :ref:`sect:turbulence`)
| ``01`` : Abundance of hydrogen (H, Z=1) in Solar units. Default 1.
| ``02`` : Abundance of helium (He, Z=2) in Solar units. Default 1.
| :math:`\ldots` ``30`` : Abundance of zinc (Zn, Z=30) in Solar units.
  Default 1.
| ``vrms`` : RMS Velocity broadening in km/s (see :ref:`sect:turbulence`)

*Recommended citation:* `Smith et al. (2001)
<https://ui.adsabs.harvard.edu/abs/2001ApJ...556L..91S/abstract>`_
and
`Foster et al. (2012)
<https://ui.adsabs.harvard.edu/abs/2012ApJ...756..128F/abstract>`_