How do I use an XSPEC user model in Sherpa?

XSPEC supports user models, that is compiled code that can be used to add new models to XSPEC. Examples can be found on the "More models for XSPEC" page. It is possible to use these models in XSPEC, although it may require making changes to the model code!

The convert_xspec_user_model contributed script will attempt to build a compiled Python module that can then be used in Sherpa. It requires two arguments - the name for the Sherpa module and the model file (often called "lmodel.dat") that defines the model (e.g. the model name, it's type, and the parameter values) - and will create and compile the code. It is similar to the XSPEC initpackage call.

As an example, using the XSTAR warm absorber mode: warmabs model, after downloading and unpacking the warmabs247.tar.gz file into its own directory, we can see from the README that

using the model requires setting the WARMABS_DATA environment variable,
the XSPEC build uses the command initpackage xstarmod lmodel.dat (sometimes changes need to be made to the source code to include the location of data files or to change various settings).

Note that the screen output is not guaranteed to match the output here: what is important to see is that it reports that the module can be loaded and what models are available.

% setenv WARMABS_DATA `pwd`
% convert_xspec_user_model xstarmod lmodel.dat
convert_xspec_user_model: 10 October 2023
  name:       xstarmod
  modelfile:  lmodel.dat
  clobber:    False

Found one Fortran file.
Found no C files.
Found no C++ files.
Processing 5 models.
Using language interface: Fortran - single precision
Using XSPEC version: 12.13.1e
Processing /download/warmabs
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: xstarmod
  Building wheel for xstarmod (pyproject.toml) ... done
  Created wheel for xstarmod: filename=xstarmod-1.0-cp311-cp311-linux_x86_64.whl size=675941 sha256=988cdb11e2c0b14640cfed185617d6d0fba960ad9c0ae27bfe34b7bd1aa2fba5
  Stored in directory: /tmp/pip-ephem-wheel-cache-woe3__i0/wheels/b0/f8/6c/84859c31235f040243f2e81f3b4cf045ccec0a41723bd9a086
Successfully built xstarmod
Installing collected packages: xstarmod
Successfully installed xstarmod-1.0

Testing out importing the model ...
Import succeeded

------------------------------------------------------------------

Finished. You should be able to now say
    import xstarmod.ui
from Sherpa.

The following 5 models are available:
  xsumhotemis
  xsumhotabs
  xsumphotemis
  xsumwarmabs
  xsummultabs

These models can now be used from any directory - i.e. you do not need to start from this directory - and can be loaded with

sherpa> import xstarmod.ui
Adding additive       XSPEC local model: xsumhotemis
Adding multiplicative XSPEC local model: xsumhotabs
Adding additive       XSPEC local model: xsumphotemis
Adding multiplicative XSPEC local model: xsumwarmabs
Adding multiplicative XSPEC local model: xsummultabs

sherpa> create_model_component("xsumwarmabs", "warm")
<XSUMwarmabs model instance 'xsumwarmabs.warm'>

sherpa> print(warm)
xsumwarmabs.warm
   Param        Type          Value          Min          Max      Units
   -----        ----          -----          ---          ---      -----
   warm.column  thawed            0           -3            2      cm^-2
   warm.rlogxi  thawed            0           -4            5           
   warm.Cabund  frozen            1            0         1000           
   warm.Nabund  frozen            1            0         1000           
   warm.Oabund  frozen            1            0         1000           
   warm.Fabund  frozen            1            0         1000           
   warm.Neabund frozen            1            0         1000           
   warm.Naabund frozen            1            0         1000           
   warm.Mgabund frozen            1            0         1000           
   warm.Alabund frozen            1            0         1000           
   warm.Siabund frozen            1            0         1000           
   warm.Pabund  frozen            1            0         1000           
   warm.Sabund  frozen            1            0         1000           
   warm.Clabund frozen            1            0         1000           
   warm.Arabund frozen            1            0         1000           
   warm.Kabund  frozen            1            0         1000           
   warm.Caabund frozen            1            0         1000           
   warm.Scabund frozen            1            0         1000           
   warm.Tiabund frozen            1            0         1000           
   warm.Vabund  frozen            1            0         1000           
   warm.Crabund frozen            1            0         1000           
   warm.Mnabund frozen            1            0         1000           
   warm.Feabund frozen            1            0         1000           
   warm.Coabund frozen            1            0         1000           
   warm.Niabund frozen            1            0         1000           
   warm.Cuabund frozen            1            0         1000           
   warm.Znabund frozen            1            0         1000           
   warm.write_outfile frozen            0            0            1           
   warm.outfile_idx frozen            0            0        10000           
   warm.vturb   frozen            0            0        10000       km/s
   warm.Redshift frozen            0            0           10

The script comes with a number of options, including changing the prefix "xsum" to "xs" or having no prefix, and support for models that require the FORTRAN udmget routine.

Note

Please contact the CXC Helpdesk if you find there are models which this script will not convert, or where the results do not appear to match XSPEC.