Skip to main content
next up previous contents
Next: Appendix G: Adding a Up: XspecManual Previous: Appendix E: Associated Programs   Contents


Appendix F: Using the XSPEC Models Library in Other Programs

For those who wish to incorporate the standard XSPEC model functions library into their own programs, XSPEC provides a set of functions and wrappers that can be called from external C, C++ or Fortran programs.

Calling Model Functions From C++, C, And Fortran

XSPEC supplies standard wrapper routines for all models from C++, C, and Fortran. The names are CXX_modelname, C_modelname, and modelname, respectively. Here modelname is the name of the model. The function interfaces for each language are described in Appendix C. The wrappers are stored in the files funcWrappers.h and funcWrappers.cxx in the XSFunctions directory.

As an example here are the wrappers for the powerlaw model. 

void CXX_powerlaw(const RealArray& energyArray, const RealArray& params,
                int spectrumNumber, RealArray& fluxArray, RealArray& fluxErrArray,
                const string& initString);
void C_powerlaw(const double* energy, int nFlux, const double* params,
                int spectrumNumber, double* flux, double* fluxError,
                const char* initStr);
void powerLaw(const float* energy, int nFlux, const float* params,
  	      int spectrumNumber, float* flux, float* fluxError);
The second function is intended to be called from C programs, while Fortran programs may call either the second or the third (funcWrappers.cxx also includes CERN <cfortran.h> definitions to make these accessible to Fortran).

Interface Routines

XSPEC also provides a set of functions for accessing some of the model functions' internal data. The C++ functions are listed in the file FunctionUtility.h in the XSFunctions/Utilities directory. For C and Fortran access, equivalent wrapper functions are listed in the same directory in xsFortran.h. The wrapper functions have C-style function declarations, and are also made available to Fortran calling routines via the CERN <cfortran.h> interface.

The currently provided C/Fortran wrapper functions are (see xsFortran.h for the function signatures):

FNINIT Initializes data directory locations needed by the models. See below for a fuller description.
FGABND Get an element abundance.
FGCHAT Get current chatter level setting for model functions' output verbosity.
FPCHAT Set the chatter level. Default is 10, higher chatter levels produce more output.
FGDATD Get the model .dat files path.
FPDATD Set the model .dat files path.
FGMODF Get the model ion data path.
FGMSTR Get a model string value (see XSPEC xset command).
FPMSTR Set a model string value.
FPSLFL Load values of a file solar abundance table (see abund command).
FGSOLR Get the solar abundance table setting.
FPSOLR Set the solar abundance table.
FGXSCT Get the cross section table setting.
FPXSCT Set the cross section table.
RFLABD Read abundance data from a file, then load and set this to be the current abundance table. (Essentially this combines a file read with the FPSLFL and FPSOLR functions.)
csmgh0 Get the cosmology H$_0$ setting (see the cosmo command).
csmph0 Set H$_0$.
csmgl0 Get $\Lambda_0$.
csmpl0 Set $\Lambda_0$.
csmgq0 Get q$_0$.
csmpq0 Put q$_0$.
fzsq Computes the luminosity distance, (c/H$_0$)*fzsq. The function is valid for small values of q$_0$*z for the case of no cosmological constant and uses the approximation of Pen (1999 ApJS 120, 49) for the case of a cosmological constant and a flat Universe. The function is not valid for non-zero cosmological constant if the Universe is not flat.
DGFILT Get a particular XFLT keyword value from a data file.
DGNFLT Get the number of XFLT keywords in a data file.
xs_getVersion (or xgvers) Retrieve XSPEC's version string.

Initializing the Models Library

The external program should always call the FNINIT routine prior to any other call into the models library. This initializes the locations of the various data files needed by the models, and also sets the abundance and cross-section tables. Unless the user has overridden the model ion data directory location with the XSPEC_MDATA_DIR environment variable, the initial settings are:

Model ion data location $HEADAS/../spectral/modelData
Abundance .dat files location $HEADAS/../spectral/manager
Cross-section .dat files location $HEADAS/../spectral/manager
Solar abundance table angr
Photoelectric cross-section table bcmc

Building with the Models Library

To build the libraries required to link in XSPEC models download XSPEC by checking the Xspec box in the HEAsoft download page and extract from the tar file. Then, in the BUILD_DIR directory: 

./configure --enable-xs-models-only
make
make install

The XSFunctions library depends on two lower-level XSPEC libraries, XS, XSUtil, and also the hdsp, CCfits and cfitsio libraries distributed with HEASOFT. A Makefile for a small Fortran program linking with the models library therefore may look like this on Linux: 

myprog : myprog.o
	g77 -g myprog.o -o myprog \
		-L/path/to/headas/installed/location/lib \
		-lXSFunctions -lXSUtil -lXS -lhdsp_2.9 -lCCfits_2.5 -lcfitsio
myprog.o: myprog.f
	g77 -g -c myprog.f

next up previous contents
Next: Appendix G: Adding a Up: XspecManual Previous: Appendix E: Associated Programs   Contents