Last modified: December 2018

URL: http://cxc.harvard.edu/sherpa/ahelp/xs.html
AHELP for CIAO 4.11 Sherpa v1

xs

Context: models

Synopsis

XSPEC model functions.

Description

Sherpa includes the "additive" and "multiplicative" models of XSPEC version 12.10.0e, 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" and the vapec model is "xsvapec".

The additive (atable) and multiplicative (mtable) XSPEC-style 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" and "etable" XSPEC components, the convolution components, and the mixing-model components of XSPEC 12.10.0e 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 Guide for 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

Model name Description
xsagauss gaussian line profile in wavelength space.
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.
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.
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.
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.
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.
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.
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.
xszagauss gaussian line profile in wavelength space.
xszbbody blackbody spectrum.
xszbremss thermal bremsstrahlung.
xszcutoffpl power law, high energy exponential cutoff.
xszgauss gaussian line profile.
xszpowerlw redshifted power law photon spectrum.

Multiplicative XSPEC models

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.
xslyman Voigt absorption profiles for H I or He II Lyman series.
xsnotch absorption line, notch.
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.
xszxipcf partial covering absorption by partially ionized material.

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       100000 10^22 atoms / cm^2
sherpa> print(pl)
xspowerlaw.pl
   Param        Type          Value          Min          Max      Units
   -----        ----          -----          ---          ---      -----
   pl.PhoIndex  thawed            1           -2            9           
   pl.norm      thawed            1            0        1e+24           

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 0, which is lower than the default value used by XSPEC itself (10). To check that the model is being evaluated correctly - e.g. in case of a probem - then the set_xschatter routine can be used to change the level. For example:

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

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.

Model values

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 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> import sherpa.astro.xspec as xspec
sherpa> print(xspec.get_xsversion())
12.10.0e

Bugs

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

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

sherpa> from sherpa.astro.xspec import get_xsversion
sherpa> get_xsversion()
'12.10.0e'

See Also

models
list_model_components, list_models, load_xscflux, load_xsclumin, load_xscpflux, load_xsgsmooth, load_xsireflect, load_xskdblur, load_xskdblur2, load_xskerrconv, load_xslsmooth, load_xspartcov, load_xsrdblur, load_xsreflect, load_xsrfxconv, load_xsrgsxsrc, load_xssimpl, load_xsvashift, load_xsvmshift, load_xsxilconv, load_xszashift, load_xszmshift, models, tablemodel, xsconvolve