    XSPEC model functions.

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

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.

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.13.1e 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.16.

Additive XSPEC models
New
Model name
Description
xsagauss
gaussian line profile in wavelength space.
xsagnsed
AGN SED model
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.
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.
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.
xsvvwdem
plasma emission, multi-temperature with power-law distribution of emission measure.
xsvwdem
plasma emission, multi-temperature with power-law distribution of emission measure.
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.
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.
xsismdust
Extinction due to a power-law distribution of dust grains.
xslog10con
Constant in base 10 log units.
xslogconst
Constant in log units.
xslyman
Voigt absorption profiles for H I or He II Lyman series.
xsnotch
absorption line, notch.
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.
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
NEW
xscglumin
calculate luminosity
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.
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):

The get_xsabund() and set_xsabund() routines.

The get_xsxsect() and set_xsxsect() routines.

The get_xscosmo() and set_xscosmo() routines.

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

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.

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.13.1e'

Changes in CIAO 4.16

The XSPEC models have been updated to release 12.13.1e in CIAO 4.16, from version 12.12.1c in CIAO 4.15. There is one new model:

Convolution: xscglumin.

The maximum limit for the redshift parameter of XSPEC table models can once again be set to a value greater than 5 (the default maximum). Support for table models that have an ESCALE parameter has been added. Unfortunately, table models NXFLTEXP greater than 1 (that is, ones with multiple spectra per set of parameter values) can not be used.

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.13.1e'

December 2023