Analytic Models

If you have a model that will be used frequently, you may want to include it among the standard models so that it will be listed after the model ? command. To do so, you first must create a subroutine that calculates the model spectrum given an input array of energy bins and an array of parameter values. The spectrum for an additive model should be in terms of photons/cm²/s (not photons/cm²/s/keV), while for a multiplicative model it is the multiplicative factor for that bin.

The six arguments in the calling sequence are EAR(0:NE), NE, PARAM(*), IFL, PHOTAR(NE), and PHOTER(NE) . EAR(0:NE) are input and are the boundaries for the NE energy bins. These are set by the response matrices of the detectors in use, so you should not make any assumptions about the values of EAR. PARAM(*) are input and are the values of the model parameters. IFL is an integer which specifies which dataset these energies are for, it exists to allow multi-dimensional models where the function might also depend on eg pulse-phase in a variable source. PHOTAR(NE) is the output array and should not be assumed to have any particular values on input. PHOTER is an array that allows the function to return model variances.

To set the default parameters and tell XSPEC that your model exists, you must add to the file lmodel.dat in a subdirectory specified by the environment variable $LMODDIR. As an example, suppose the model newmodel with 3 parameters is implemented with the fortran 77 subroutine newfunc with

    SUBROUTINE NEWFUNC(EAR,NE,PARAM,IFL,PHOTAR,PHOTER)
    INTEGER IFL, NE
    REAL*4 EAR(0:NE), PARAM(*), PHOTAR(NE), PHOTER(NE)
    ...
    
    END

The corresponding lmodel.dat entry is:

newmodel        3  0.         1.e20           newfunc    add  0
kT      keV     1.    0.008   0.008   64.0      64.0      .01
Abundanc " "    1.    0.      0.      5.        5.        -0.001
Redshift " "    0.    0.      0.      2.        2.        -0.001

The first line for each model gives the model name, the number of parameters, the low and high energies for which the model is valid, the name of the subroutine in the functions subdirectory, and the type of model (add, mul, mix, or con). The final argument is a flag which should be set to 1 if PHOTER is calculated by NEWFUNC.

There then should be one succeeding line for each parameter. Each line contains the parameter name, a default starting value, the hard minimum, the soft minimum, the soft maximum, the hard maximum, and the initial delta. If there is more than one model in the lmodel.dat file their entries should be separated by a single blank line.

Linking User-Defined Analytic models to XSPEC

The object of the updated local model implementation in XSPEC V11 is to remove the need for users to build personal copies of XSPEC. Instead, the user should be able to define a directory that contains their models, build a library from it that contains the functions XSPEC uses to recognize valid model components, and link the system-wide version of XSPEC to that library by setting appropriate environment variables.

Note that you must have installed the source distribution (not binary) to do this.

At Installation Time

To build and install local models directly into a full Xspec build, use the following procedure. Prior to starting the build, type (csh, tcsh):

setenv LMODDIR /path/to/your/local/model/code

or

LMODDIR=/path/to/your/local/model/code
export LMODDIR

in Bourne-type shells (sh, bash, ksh). Then proceed with the standard build instructions. This will create a library in the directory $LMODDIR that XSPEC will link to at runtime. Note that you must have $LMODDIR defined whenever you run XSPEC with your local models.

Using your own models in a site-installed version of XSPEC

To build and use local models in a private directory, after XSPEC has been installed perform the standard HEASOFT setup:

setenv HEADAS /path/to/installed/xspec/ending/in/ARCHDIR
source $HEADAS/headas-init.csh

(and similarly for Bourne shell and variants), where ARCHDIR is the architecture-specific directory containing the installed software (e.g. Linux_2.2_i686 for a Pentium-II based PC running the Linux 2.2 kernel, as supplied with RedHat Linux 6.x, or SunOS_5.6_sparc for Solaris 2.6). If headas-init.csh does not exist and you have write permission in your local site distribution then you should define HEADAS as above and then try :

cd $HEADAS/BUILD_DIR
./configure

before sourcing $HEADAS/headas-init.csh. Now, to build your local models, type:

setenv LMODDIR /path/to/your/local/models/code

then cd to the directory:

$HEADAS/../spectral/xspec/src/local_mod

and type ``hmake''. This should build your local models in the $LMODDIR directory. N.B. Files named Makefile and setup.dat will be copied into the directory given by $LMODDIR, so if you have files with those names, please back them up. Also, note that if there are any site-wide installed local models, you will not be able to use these unless you copy their code and lmodel.dat entries into your $LMODDIR directory.

If all goes well, at the conclusion of this step, $LMODDIR will contain a file called libxspec_lfn.so, which is a shared library containing the local model code. Finally add $LMODDIR to the LD_LIBRARY_PATH environment variable. For C shell variants, type:

setenv LD_LIBRARY_PATH "${LMODDIR}:${LD_LIBRARY_PATH}"

or for Bourne shell variants:

LD_LIBRARY_PATH="$LMODDIR:$LD_LIBRARY_PATH"
export LD_LIBRARY_PATH

This step must be performed manually by the user, but may be added to the .login/.profile file. Note that you must have $LMODDIR defined whenever you run XSPEC with your local models.

Under Solaris and Linux you can check whether XSPEC is using your local library using

ldd `which xspec`

A special note for Mac OS X users

On Mac OS X we cannot currently compile a shared library for the local models. In this case local models cannot be added to a site version to which you do not have access. If you do have permission to overwrite the xspec11 executable you can include local models as follows :

cd $HEADAS/../

(or cd /path/to/your/headas/ if you gave a prefix to configure)

cd ftools/spectral/xspec/src/
rm local_mod/libxspec_lfn*
rm xspec11
hmake xspec11
hmake install