Last modified: December 2021

URL: https://cxc.cfa.harvard.edu/sherpa/ahelp/xs.html
AHELP for CIAO 4.14 Sherpa

xs

Context: models

Synopsis

XSPEC model functions.

Description

Sherpa in CIAO 4.14 includes the "additive", "multiplicative", and "convolution" models of XSPEC version 12.12.0, 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" model and the mixing-model components of XSPEC 12.12.0 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.14.

Additive XSPEC models

New Model name Description
xsagauss gaussian line profile in wavelength space.
xsagnsed AGN SED model
NEW xsagnslim AGN super-Eddington accretion model
xsapec APEC emission spectrum.
xsbapec velocity broadened APEC thermal plasma model.
xsbbody blackbody spectrum.
xsbbodyrad blackbody spectrum, area normalized.
xsbexrav reflected e-folded broken power law, neutral medium.
xsbexriv reflected e-folded broken power law, ionized medium.
xsbkn2pow broken power law with two breaks.
xsbknpower broken power law.
xsbmc Comptonization by relativistic matter.
xsbremss thermal bremsstrahlung.
xsbrnei velocity-broadened non-equilibrium recombining collisional plasma.
xsbtapec velocity broadened APEC emission spectrum with separate continuum and line temperatures.
xsbvapec velocity broadened APEC thermal plasma model.
xsbvrnei velocity-broadened non-equilibrium recombining collisional plasma.
xsbvtapec velocity broadened APEC emission spectrum with separate continuum and line temperatures.
xsbvvapec velocity broadened APEC thermal plasma model.
xsbvvrnei velocity-broadened non-equilibrium recombining collisional plasma.
xsbvvtapec velocity broadened APEC emission spectrum with separate continuum and line temperatures.
NEW xsbwcycl Becker-Wolff self-consistent cyclotron line model.
xsc6mekl differential emission measure using Chebyshev representations with multi-temperature mekal.
xsc6pmekl differential emission measure using Chebyshev representations with multi-temperature mekal.
xsc6pvmkl differential emission measure using Chebyshev representations with multi-temperature mekal.
xsc6vmekl differential emission measure using Chebyshev representations with multi-temperature mekal.
xscarbatm Nonmagnetic carbon atmosphere of a neutron star.
xscemekl plasma emission, multi-temperature using mekal.
xscevmkl plasma emission, multi-temperature using mekal.
xscflow cooling flow.
xscompbb Comptonization, black body.
xscompls Comptonization, Lamb & Sanford.
xscompmag Thermal and bulk Comptonization for cylindrical accretion onto the polar cap of a magnetized neutron star.
xscompps Comptonization, Poutanen & Svenson.
xscompst Comptonization, Sunyaev & Titarchuk.
xscomptb Thermal and bulk Comptonization of a seed blackbody-like spectrum.
xscompth Paolo Coppi's hybrid (thermal/non-thermal) hot plasma emission models.
xscomptt Comptonization, Titarchuk.
xscph Cooling + heating model for cool core clusters
xscplinear a non-physical piecewise-linear model for low count background spectra.
xscutoffpl power law, high energy exponential cutoff.
xsdisk accretion disk, black body.
xsdiskbb accretion disk, multi-black body components.
xsdiskir Irradiated inner and outer disk.
xsdiskline accretion disk line emission, relativistic.
xsdiskm accretion disk with gas pressure viscosity.
xsdisko accretion disk, inner, radiation pressure viscosity.
xsdiskpbb accretion disk, power-law dependence for T(r).
xsdiskpn accretion disk, black hole, black body.
xseplogpar log-parabolic blazar model with nu-Fnu normalization.
xseqpair Paolo Coppi's hybrid (thermal/non-thermal) hot plasma emission models.
xseqtherm Paolo Coppi's hybrid (thermal/non-thermal) hot plasma emission models.
xsequil collisional plasma, ionization equilibrium.
xsexpdec exponential decay.
xsezdiskbb multiple blackbody disk model with zero-torque inner boundary.
xsgadem plasma emission, multi-temperature with gaussian distribution of emission measure.
xsgaussian gaussian line profile.
xsgnei collisional plasma, non-equilibrium, temperature evolution.
xsgrad accretion disk, Schwarzschild black hole.
xsgrbcomp Comptonization for GRB prompt emission.
NEW xsgrbjet Two-phase Comptonization model of soft thermal seed photons for GRB prompt emission
xsgrbm gamma-ray burst continuum.
xshatm Nonmagnetic hydrogen atmosphere of a neutron star.
xsjet Leptonic relativistic jet model.
xskerrbb multi-temperature blackbody model for thin accretion disk around a Kerr black hole.
xskerrd optically thick accretion disk around a Kerr black hole.
xskerrdisk accretion disk line emission with BH spin as free parameter.
xskyrline relativistic line from axisymmetric accretion disk
xslaor accretion disk, black hole emission line.
xslaor2 accretion disk with broken-power law emissivity profile, black hole emission line.
xslogpar log-parabolic blazar model.
xslorentz lorentz line profile.
xsmeka emission, hot diffuse gas (Mewe-Gronenschild).
xsmekal emission, hot diffuse gas (Mewe-Kaastra-Liedahl).
xsmkcflow cooling flow, mekal.
xsnei collisional plasma, non-equilibrium, constant temperature.
xsnlapec continuum-only APEC emission spectrum.
xsnpshock shocked plasma, plane parallel, separate ion, electron temperatures.
xsnsa neutron star atmosphere.
xsnsagrav NS H atmosphere model for different g.
xsnsatmos NS Hydrogen Atmosphere model with electron conduction and self-irradiation.
xsnsmax Neutron Star Magnetic Atmosphere.
xsnsmaxg neutron star with a magnetic atmosphere.
xsnsx neutron star with a non-magnetic atmosphere.
xsnteea non-thermal pair plasma.
xsnthcomp Thermally comptonized continuum.
xsoptxagn Colour temperature corrected disc and energetically coupled Comptonisation model for AGN.
xsoptxagnf Colour temperature corrected disc and energetically coupled Comptonisation model for AGN.
xspegpwrlw power law, pegged normalization.
xspexmon neutral Compton reflection with self-consistent Fe and Ni lines.
xspexrav reflected powerlaw, neutral medium.
xspexriv reflected powerlaw, neutral medium.
xsplcabs powerlaw observed through dense, cold matter.
xsposm positronium continuum.
xspowerlaw power law photon spectrum.
xspshock plane-parallel shocked plasma, constant temperature.
xsqsosed AGN SED model
xsraymond emission, hot diffuse gas, Raymond-Smith.
xsredge emission, recombination edge.
xsrefsch reflected power law from ionized accretion disk.
xsrnei non-equilibrium recombining collisional plasma.
xssedov sedov model, separate ion/electron temperature.
xssirf self-irradiated funnel.
xsslimbh Stationary slim accretion disk.
xssnapec galaxy cluster spectrum using SN yields.
xssrcut synchrotron spectrum, cutoff power law.
xssresc synchrotron spectrum, cut off by particle escape.
xsssa Strangeon star atmosphere.
xsstep step function convolved with gaussian.
xstapec APEC emission spectrum with separate continuum and line temperatures.
xsvapec APEC emission spectrum.
xsvbremss thermal bremsstrahlung.
xsvcph Cooling + heating model for cool core clusters
xsvequil collisional plasma, ionization equilibrium.
xsvgadem plasma emission, multi-temperature with gaussian distribution of emission measure.
xsvgnei collisional plasma, non-equilibrium, temperature evolution.
xsvmcflow cooling flow, mekal.
xsvmeka emission, hot diffuse gas (Mewe-Gronenschild).
xsvmekal emission, hot diffuse gas (Mewe-Kaastra-Liedahl).
xsvnei collisional plasma, non-equilibrium, constant temperature.
xsvnpshock shocked plasma, plane parallel, separate ion, electron temperatures.
xsvoigt Voigt line profile.
xsvpshock plane-parallel shocked plasma, constant temperature.
xsvraymond emission, hot diffuse gas, Raymond-Smith.
xsvrnei non-equilibrium recombining collisional plasma.
xsvsedov sedov model, separate ion/electron temperature.
xsvtapec APEC emission spectrum with separate continuum and line temperatures.
xsvvapec APEC emission spectrum.
xsvvgnei collisional plasma, non-equilibrium, temperature evolution.
xsvvnei collisional plasma, non-equilibrium, constant temperature.
xsvvnpshock shocked plasma, plane parallel, separate ion, electron temperatures.
xsvvpshock plane-parallel shocked plasma, constant temperature.
xsvvrnei non-equilibrium recombining collisional plasma.
xsvvsedov sedov model, separate ion/electron temperature.
xsvvtapec APEC emission spectrum with separate continuum and line temperatures.
NEW xsvvwdem plasma emission, multi-temperature with power-law distribution of emission measure.
NEW xsvwdem plasma emission, multi-temperature with power-law distribution of emission measure.
NEW xswdem plasma emission, multi-temperature with power-law distribution of emission measure.
xszagauss gaussian line profile in wavelength space.
xszbbody blackbody spectrum.
xszbknpower broken power law.
xszbremss thermal bremsstrahlung.
xszcutoffpl power law, high energy exponential cutoff.
xszgauss gaussian line profile.
NEW xszkerrbb multi-temperature blackbody model for thin accretion disk around a Kerr black hole.
xszlogpar log-parabolic blazar model.
xszpowerlw redshifted power law photon spectrum.

Multiplicative XSPEC models

New Model name Description
xsabsori ionized absorber.
xsacisabs Chandra ACIS q.e. decay.
xscabs Optically-thin Compton scattering.
xsconstant energy-independent factor.
xscyclabs absorption line, cyclotron.
xsdust dust scattering.
xsedge absorption edge.
xsexpabs exponential roll-off at low E.
xsexpfac exponential modification.
xsgabs gaussian absorption line.
xsheilin Voigt absorption profiles for He I series.
xshighecut high-energy cutoff.
xshrefl reflection model.
xsismabs A high resolution ISM absorption model with variable columns for individual ions.
NEW xsismdust Extinction due to a power-law distribution of dust grains.
NEW xslog10con Constant in base 10 log units.
NEW xslogconst Constant in log units.
xslyman Voigt absorption profiles for H I or He II Lyman series.
xsnotch absorption line, notch.
NEW xsolivineabs Absorption due to olivine.
xspcfabs partial covering fraction absorption.
xsphabs photoelectric absorption.
xsplabs power law absorption.
xspwab power-law distribution of neutral absorbers.
xsredden interstellar extinction.
xssmedge smeared edge.
xsspexpcut super-exponential cutoff absorption.
xsspline spline modification.
xssss_ice Einstein SSS ice absorption.
xsswind1 absorption by partially ionized material with large velocity shear.
xstbabs ISM grain absorption.
xstbfeo ISM grain absorption.
xstbgas ISM grain absorption.
xstbgrain ISM grain absorption.
xstbpcf ISM grain absorption.
xstbrel ISM grain absorption.
xstbvarabs ISM grain absorption.
xsuvred interstellar extinction, Seaton Law.
xsvarabs photoelectric absorption.
xsvphabs photoelectric absorption.
xswabs photoelectric absorption, Wisconsin cross-sections.
xswndabs photo-electric absorption, warm absorber.
xsxion reflected spectrum of photo-ionized accretion disk/ring.
xsxscat dust scattering.
xszbabs EUV ISM attenuation.
xszdust extinction by dust grains.
xszedge absorption edge.
xszhighect high-energy cutoff.
xszigm UV/Optical attenuation by the intergalactic medium.
xszpcfabs partial covering fraction absorption.
xszphabs photoelectric absorption.
xszredden redshifted version of redden.
xszsmdust extinction by dust grains in starburst galaxies.
xsztbabs ISM grain absorption.
xszvarabs photoelectric absorption.
xszvfeabs photoelectric absorption with free Fe edge energy.
xszvphabs photoelectric absorption.
xszwabs photoelectric absorption, Wisconsin cross-sections.
xszwndabs photo-electric absorption, warm absorber.
NEW xszxipab power-law distribution of ionized absorbers.
xszxipcf partial covering absorption by partially ionized material.

Convolution XSPEC models

New Model name Description
xscflux calculate flux
xsclumin calculate luminosity
xscpflux calculate photon flux
xsgsmooth gaussian smoothing
xsireflect reflection from ionized material
xskdblur convolve with the laor model
xskdblur2 convolve with the laor2 model
xskerrconv accretion disk line shape with BH spin as free parameter
xskyconv convolution using a relativistic line from axisymmetric accretion disk
xslsmooth lorentzian smoothing
xspartcov partial covering
xsrdblur convolve with the diskline model shape
xsreflect reflection from neutral material
xsrfxconv angle-dependent reflection from an ionized disk
xsrgsxsrc convolve an RGS spectrum for extended emission.
xssimpl comptonization of a seed spectrum.
NEW xsthcomp Thermally comptonized continuum.
xsvashift velocity shift an additive model.
xsvmshift velocity shift a multiplicative model.
xsxilconv angle-dependent reflection from an ionized disk
xszashift redshift an additive model.
xszmshift redshift a multiplicative model.

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.0'

Changes in CIAO 4.14

XSPEC model updates

The XSPEC models have been updated to release 12.12.0 in CIAO 4.14, from version 12.10.1s in CIAO 4.13. There are a number of new models:

Parameter changes

The parameter limits - that is the "Min" and "Max" values reported by the print call - have been changed in CIAO 4.14 to use the XSPEC "hard-limit" range rather than the XSPEC "soft-limit" range which was used in earlier versions. This can lead to changes to fit results, and in routines like sample_energy_flux, for parameter values that are not well constrained.

For those rare models that require it, it is now possible to change the minimum and maximum range of XSPEC parameters by changing the hard_min or hard_max attribute of the parameter's set method.

The default chatter setting

In CIAO 4.14 the default chatter setting is now 10, matching the default behavior of XSPEC, rather than 0. This means that the first time a model is evaluated you may see extra output, but it should also help point out if your ~/.xspec/Xspec.init file needs updating (e.g. for the ATOMDB_VERSION and NEI_VERSION settings).


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.0'

See Also

models
list_model_components, list_models, models, tablemodel