Chandra X-Ray Observatory
Skip to the navigation links
Last modified: 25 Jan 2017


Using X-Spec User Models in Sherpa

Sherpa Threads (CIAO 4.9 Sherpa v1)



The experimental script convert_xspec_user_model provides support for using some X-Spec contributed models—whether written youself or obtained from the new X-Spec models page—from Sherpa.

Last Update: 25 Jan 2017 - Updated for CIAO 4.9; convolution models are still not supported.


Setting up

The convert_xspec_user_model script is provided as part of the CIAO contributed-scripts package.

For the purposes of the thread, version 1.2 of the ismabs model will be used. The file ismabs.v1.2.tgz is assumed to have been downloaded and unpacked; for example:

unix% cd /data/models/ISMabs
unix% tar xzf ismabs.v1.2.tgz
unix% ls -1F

Compiling the user model

The convert_xspec_user_model script is similar to the X-Spec initpackage command, so follow the model instructions to make any changes before running initpackage, and then run convert_xspec_user_model instead.

Setting up the model

For version 1.2 of the ismabs model, the instructions say to use the script, which edits the ismabs.f90 file and then calls initpackage. The configuration step is done manually here, taken from the

unix% sed -i "s,local_dir = '.*',local_dir = \'`pwd`\'," ismabs.f90

Many models require no set up or code changes.

Compile the model

After any setup, the convert_xspec_user_model script is used to compile the model. For many cases you just need a name for the Python module containing the model, or models, and the name of the "model.dat" file. In this case we use ismabs for the model name; this will be used to load in the model for testing later.

unix% convert_xspec_user_model ismabs lmodel.dat
Found one Fortran file.
Found no C files.
Found no C++ files.
Processing one model.
Using language interface: Fortran - single precision
Created: ismabs/
Created: ismabs.pyf
Compiling module
... a lot of screen output 

Testing out importing the model ...
Import succeeded


Finished. You should be able to now say
    import ismabs
from Sherpa, or
    from sherpa_contrib.xspec.local import lmod
    lmod("ismabs", "/data/models/ISMabs")
to load the model from a different directory.

The following model is available:

If the script gets this far—that is, the model can be imported and a message listing the available model, or models, is displayed—then the model has compiled and you can check it out in Sherpa. Otherwise, follow on to the errors section.

What to do if the build fails

There are a number of reasons why the build might fail; please contact the CXC Helpdesk if you are unable to solve the problem. The --clobber may be needed if convert_xspec_user_model is called multiple times.

  1. In CIAO 4.8, Only additive and multiplicative models are supported. Convolution model support will be added in a later release.

  2. There is currently no support for models that require the -udmget flag when calling X-Spec's initpackage command.

  3. There can be problems if your version of gcc and gfortran is much different than the version used to build CIAO 4.9 (gcc version 4.2 or 4.4 depending on the platform). This can lead to link errors such as

    undefined symbol: _gfortran_copy_string
  4. The script does not guarantee to compile files in the same order as X-Spec does, so if an ordering is required, then the build may fail.

  5. If there are link or build issues, then the flags --no-xspec and --cfitsio may be useful: --no-xspec means that no X-Spec libraries are linked to and --cfitsio can be added if the model only uses the CFITSIO routines.

    There may also be a version conflict between the X-Spec version needed by the model and that provided by Sherpa, which uses version 12.9.0o in CIAO 4.9.

Testing the model in Sherpa

Once the model has been compiled, it can be used from Sherpa. For the ismabs model, we can try it without any data or response information using the following. First, load in the module (if you are in the same directory as the module then the second argument to lmod can be dropped, otherwise replace /data/models/ISMabs with the location of your model):

sherpa> from sherpa_contrib.xspec.local import lmod
sherpa> lmod("ismabs", "/data/models/ISMabs")
Loaded: ismabs

There is one multiplicative model:

Now we create a simple data space over which the model can be evaluated and the model expression (note that the user model, xsismabs is used in the same manner as the build-in models):

sherpa> dataspace1d(0.1, 10, step=0.01, id=1, dstype=Data1DInt)
sherpa> set_source( *
sherpa> show_source()
( *
   Param        Type          Value          Min          Max      Units
   -----        ----          -----          ---          ---      -----
   gal.H        thawed          0.1            0       100000      10^22
   gal.HeII     frozen            0            0       100000      10^16
   gal.CI       thawed         33.1            0       100000      10^16
   gal.CII      frozen            0            0       100000      10^16
   gal.CIII     frozen            0            0       100000      10^16
   gal.NI       thawed         8.32            0       100000      10^16
   gal.NII      frozen            0            0       100000      10^16
   gal.NIII     frozen            0            0       100000      10^16
   gal.OI       thawed         67.6            0       100000      10^16
   gal.OII      frozen            0            0       100000      10^16
   gal.OIII     frozen            0            0       100000      10^16
   gal.NeI      thawed           12            0       100000      10^16
   gal.NeII     frozen            0            0       100000      10^16
   gal.NeIII    frozen            0            0       100000      10^16
   gal.MgI      thawed          3.8            0       100000      10^16
   gal.MgII     frozen            0            0       100000      10^16
   gal.MgIII    frozen            0            0       100000      10^16
   gal.SiI      linked            0            expr: gal.SII      10^16
   gal.SiII     linked            0           expr: gal.SIII      10^16
   gal.SiIII    frozen            0            0       100000      10^16
   gal.SI       thawed         2.14            0       100000      10^16
   gal.ArI      thawed         0.25            0       100000      10^16
   gal.ArII     frozen            0            0       100000      10^16
   gal.ArIII    frozen            0            0       100000      10^16
   gal.CaI      thawed         0.22            0       100000      10^16
   gal.CaII     frozen            0            0       100000      10^16
   gal.CaIII    frozen            0            0       100000      10^16
   gal.Fe       thawed         3.16            0       100000      10^16
   gal.redshift frozen            0            0           10           
   pl.PhoIndex  thawed            1           -2            9           
   pl.norm      thawed            1            0        1e+24           

Parameter names

The parameter names specified in the X-Spec "model.dat" file are not always valid for Python, so a transformation is made, converting unusable characters—such as + and /—into the underscore character (_).

Two versions of the model are now plotted on the same graph; first for the default parameter values and then after changing the C_0 parameter, which creates Figure 1:

sherpa> plot_source()
 ISMabs: ISM absorption model Version0.1a                                    
 Gatuzz, Garcia, Kallman, Mendoza, & Gorczyca (2014)
 Note: Default column densities are given
 according to Grevesse, N. & Sauval (1998)
 assuming N_H = 1.E21 cm^-2
 Loading atomic-data for dataset           1
sherpa> gal.CI = 100
sherpa> plot_source(overplot=True)
sherpa> set_curve(['*.color', 'slategray'])
sherpa> log_scale()
sherpa> limits(Y_AXIS, 1e-4, 0.02)
sherpa> limits(X_AXIS, 0.2, 10)
[The two curves only differ in the range x=0.3 to 2, where the second model is lower than the first]

[Version: PNG]

[Print media version: The two curves only differ in the range x=0.3 to 2, where the second model is lower than the first]

Figure 1: Comparison of two model plots

The red line shows the model using the default parameters, whereas the gray line shows the model after increasing the CI parameter to 100.

Since there is no response information here—as no RMF has been loaded—then the axes have no units.

External files or configuration

Many models require, or allow, external configuration. The set_xsxset command is the equivalent of X-Spec's xset command. As an example:

sherpa> set_xsxset('CARBATM', '/data/models/data/carbatm')

sets the X-Spec CARBATM variable.

The equivalent location to X-Spec's spectral/ directory is $ASCDS_INSTALL/ots/spectral/.


30 Sep 2014 original version
15 Dec 2014 Updated for CIAO 4.7
29 Feb 2016 Updated for CIAO 4.8 and contributed scripts 4.8.2
25 Jan 2017 Updated for CIAO 4.9; convolution models are still not supported.

Last modified: 25 Jan 2017
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email: Smithsonian Institution, Copyright © 1998-2017. All rights reserved.