xs

Synopsis

XSPEC model functions.

Description

Sherpa in CIAO 4.15 includes the "additive", "multiplicative", and "convolution" models of XSPEC version 12.12.1c, 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.

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.12.1c 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.

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() and set_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.12.1c'

Changes in CIAO 4.15

XSPEC model updates

The XSPEC models have been updated to release 12.12.1c in CIAO 4.14, from version 12.12.0 in CIAO 4.14.

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.12.1c'

See Also

models

list_model_components, list_models, models, tablemodel