xs

Synopsis

XSPEC model functions.

Description

Sherpa in CIAO 4.17 includes the "additive", "multiplicative", and "convolution" models of XSPEC version 12.14.0k, and are available by adding the prefix "xs" before the XSPEC model name (in lower case). As examples: in Sherpa the XSPEC phabs model is called "xsphabs", the vapec model is "xcvapec", and the cflux model is "xscflux".

XSPEC table models

The additive (atable), multiplicative (mtable), and exponential (etable) XSPEC table models are supported by the load_xstable_model command. Models that provide redshift and escale parameters are supported, but those models with multiple spectra per set of parameters (where the NXFLTEXP keyword is set to a value greater than 1) are not.

Important note:

XSPEC models based on physical processes (e.g. line models such as raymond or absorption models such as wabs) assume that the dataspace is defined in keV. On the other hand, Sherpa models are always calculated based on the input data scale. Thus when XSPEC models are combined with Sherpa models, the user should be careful to ensure that both components have the same dataspace units; otherwise, calculated model amplitudes may be incorrect.

These models also expect that the x-values will always be energy bins. When the analysis setting is using non-energy bins and an XSPEC model is defined, Sherpa converts the bins to energy before sending them to the XSPEC model. After the XSPEC model finishes, Sherpa converts back to the original units. Sherpa also scales the model values appropriately (e.g., if counts/keV came out of the XSPEC model and Sherpa is working with wavelength, then Sherpa scales the output of the XSPEC model to counts/Angstrom).

Unavailable XSPEC models

The "smaug", "polconst", "pollin", and "polpow" models, and the mixing-model components of XSPEC 12.14.0k are NOT included in CIAO.

Available XSPEC models

The available XSPEC models are listed below. Refer to the ahelp page for each model (e.g. "ahelp xsabsori") or the XSPEC User's Guidefor more information. Note that the ahelp files describe the version of the XSPEC model included in CIAO, while the XSPEC User's Guide may reference a newer version with different options. If the first column is labelled NEW then the model is new to CIAO 4.17.

Additive XSPEC models

Multiplicative XSPEC models

Convolution XSPEC models

Parameter names

Sherpa uses names, rather than numbers, to access parameter values (e.g. to set them, change whether a parameter is frozen, adjust the limits, or access the latest value). Prior to XSPEC version 12.9.0, the parameter names for the XSPEC models were not guaranteed to be valid Python symbols, and so Sherpa has converted the problematic names. The names used by Sherpa are given in the ahelp page for the model - e.g.ahelp xspowerlaw- and by printing the model component:

sherpa> set_source(xsphabs.gal * xspowerlaw.pl)
sherpa> print(gal)
xsphabs.gal
   Param        Type          Value          Min          Max      Units
   -----        ----          -----          ---          ---      -----
   gal.nH       thawed            1            0        1e+06 10^22 atoms / cm^2
sherpa> print(pl)
xspowerlaw.pl
   Param        Type          Value          Min          Max      Units
   -----        ----          -----          ---          ---      -----
   pl.PhoIndex  thawed            1           -3           10
   pl.norm      thawed            1            0        1e+24
    

Parameter limits

A small number of XSPEC models support parameter values outside the XSPEC hard-limit range, such as the fpl parameter of xsoptxagn, which can be set to a negative value. To support these models the hard-limits can be changed for an XSPEC parameter with the hard_min and hard_max arguments to the set method:

sherpa> create_model_component('xsoptxagn', 'cpt')
sherpa> cpt.fpl.min
0.0
sherpa> cpt.fpl.set(hard_min=-1)
sherpa> cpt.fpl.min
-1.0

It is strongly suggested that the parameter is frozen when it is set outside the original limits.

Changing the chatter level of XSPEC models

The default chatter level for XSPEC models - i.e. how much information they will print to the screen when evaluated - is set to 10, matching the default XSPEC version. The chatter setting can be changed with set_xschatter - for example:

sherpa> set_xschatter(0)
sherpa> plot_fit()
sherpa> set_xschatter(10)

The current XSPEC chatter level is returned by the get_xschatter level.

The Python docstrings for these functions provide more information, and can be read with the help() function:

sherpa> help(set_xschatter)
sherpa> help(get_xschatter)

Accessing the XSPEC state

Several routines are provided to change (or report) the XSPEC state (i.e. settings that may influence the model calculations). These include (please use the Python help command for more information on these functions):

Abundance

The get_xsabund(), set_xsabund(), get_xsabundances(), set_xsabundances(), and show_xsabund() routines.

Cross section

The get_xsxsect() and set_xsxsect() routines.

Cosmology

The get_xscosmo() and set_xscosmo() routines.

Using the SET command

The XSPEC SET command is handled by the set_xsxset() routine, and once a value is set it can be retrieved with get_xsxset().

Manager and model paths

The sherpa.astro.xspec module contains the get_xspath_manager() and get_xspath_model() to return the current paths to the XSPEC directories, and set_xspath_manager() to change the path.

All XSPEC settings

The sherpa.astro.xspec module contains the get_xsstate() and set_xsstate() routines which can be used to find and set all of the above values.

Checking the XSPEC module version

The XSPEC module contains the get_xsversion routine, which returns a string containing the XSPEC patch level used in Sherpa. As an example:

sherpa> from sherpa.astro import xspec
sherpa> xspec.get_xsversion()
'12.14.0k'

Changes in CIAO 4.17

XSPEC model updates

The XSPEC models have been updated to release 12.14.0k in CIAO 4.17, from version 12.13.1e in CIAO 4.16. There are 50 new additive models, although a number of them are essentially just renamed versions of existing models (see the XSPEC model documentation for more details):

• xsbcempow, xsbcheb6, xsbcie, xsbcoolflow, xsbcph, xsbequil, xsbexpcheb6, xsbgadem, xsbgnei, xsbnei, xsbnpshock, xsbpshock, xsbsedov, xsbsnapec, xsbvcempow, xsbvcheb6, xsbvcie, xsbvcoolflow, xsbvcph, xsbvequil, xsbvexpcheb6, xsbvgadem, xsbvgnei, xsbvnei, xsbvnpshock, xsbvpshock, xsbvsedov, xsbvvcie, xsbvvgadem, xsbvvgnei, xsbvvnei, xsbvvnpshock, xsbvvpshock, xsbvvsedov, xsbvvwdem, xsbvwdem, xsbwdem, xscempow, xscheb6, xscie, xscoolflow, xseebremss, xsexpcheb6, xsvcempow, xsvcheb6, xsvcie, xsvcoolflow, xsvexpcheb6, xsvvcie, xsvvgadem.

Changes to default parameter values

The default parameter values of a number of models have been adjusted to match changes made in XSPEC 12.14.0. Of particular note are models which now use a default redshift if 0.1 rather than 0, and models with a switch parameter which now default to 2 rather than 1 (indicating the use of APEC for interpolation rather than mekal). The switch parameter may also now have an upper limit of 3, indicating the use of SPEX data for the interpolation, rather than 2. Several models have seen some parameters marked as frozen or thawed to match XSPEC 12.14.0. Please see the individual model ahelp pages for more information.

Parameter name changes

A number of models now use the XSPEC capitalization for the redshift parameter (that is, 'redshift' or 'Redshift', depending on the model). Since Sherpa's parameter interface is case insensitive this does not change the behaviour of Sherpa scripts, but screen or file output will use the new capitalization.

Abundance settings

The show_xsabund(), get_xsabundances() and set_xsabundances() commands have been added in this release. They allow users to get, set, or see all the abundances in one go - rather than the existing get_xsabund() and set_xsabund() commands, which support a pre-set table or access by an individual element.

Bugs

For a list of known bugs and issues with the XSPEC models, please visit theXSPEC bugs page.

To check the XSPEC version used by Sherpa, use the get_xsversion routine from the xspec module:

sherpa> from sherpa.astro import xspec
sherpa> xspec.get_xsversion()
'12.14.0k'

See Also

models

list_model_components, list_models, models, tablemodel