This tutorial covers the steps to build a "complete" standalone installation of Sherpa which includes everything needed to do X-ray analysis. This was tested on Mac OS 10.6 with EPD Python and also includes specific issues that came up when installing on a CentOS 5.4 linux system (with no root access) using a custom-built python 2.7. Note that if you don't want to do X-ray analysis then the instructions on the Sherpa page will be sufficient and you don't need to follow the directions below.

Download standalone Sherpa

The starting point is the Sherpa standalone page http://cxc.harvard.edu/contrib/sherpa and the requirements stated therein. Download and untar the installation tarball into a scratch directory.

Download CIAO libraries

The easiest way to get all the optional libraries is just to download the CIAO binaries. You might ask why bother with standalone Sherpa if you are just linking against CIAO binaries. The point is that you get to retain your own python (which in my case has a substantial installation 3rd party libraries) and add Sherpa instead of starting with the Sherpa python and adding libraries.

Go to the CIAO download page and fill in the form. Make sure to explicitly select the platform that matches your python installation. To build standalone Sherpa you only need

  • CIAO analysis tools
  • Sherpa modeling and fitting package
  • Contributed scripts

Follow the instructions to install CIAO. Note that the CIAO install script puts everything into <INSTALL_DIR>/ciao-4.x where <INSTALL_DIR> is the installation directory that you specify. In the rest of the tutorial it is assumed that you've done something like:

set CIAO=<INSTALL_DIR>/ciao-4.5 # tcsh/csh
CIAO=<INSTALL_DIR>/ciao-4.5 # bash

Build

Now you are ready to build. From within the untarred sherpa directory do:

python setup.py \
fftw_library_dir=${CIAO}/ots/lib \
fftw_include_dir=${CIAO}/ots/include \
cfitsio_library_dir=${CIAO}/ots/lib \
xspec_library_dir=${CIAO}/ots/lib \
reg_library_dir=${CIAO}/lib \
reg_include_dir=${CIAO}/include \
wcs_library_dir=${CIAO}/ots/lib \
wcs_include_dir=${CIAO}/ots/include \
fortran_lib=gfortran \
fortran_library_dir=${CIAO}/lib \
install

If it doesn't succeed with the build then you may need to use the custom setup.py script. On CentOS-5.4 I found that some libraries were using symbols defined in libgfortran.so but that it was not being linked in even when I used the fortran_lib option. To work around this I hacked the setup.py to let me insist on an additional library and library_dir. With the patched setup.py try this:

python setup.py \
fftw_library_dir=${CIAO}/lib \
fftw_include_dir=${CIAO}/include \
cfitsio_library_dir=${CIAO}/ots/lib \
xspec_library_dir=${CIAO}/ots/lib \
reg_library_dir=${CIAO}/lib \
reg_include_dir=${CIAO}/include \
wcs_library_dir=${CIAO}/ots/lib \
wcs_include_dir=${CIAO}/ots/include \
cpp_lib=gfortran \
cpp_library_dir=${CIAO}/lib \
install

You may also need to include ${CIAO}/lib and ${CIAO}/ots/lib in your
 LD_LIBRARY_PATH or DYLD_LIBRARY_PATH environment variable.

setenv LD_LIBRARY_PATH ${CIAO}/lib:${CIAO}/ots/lib # linux
setenv DYLD_LIBRARY_PATH ${CIAO}/lib:${CIAO}/ots/lib # mac

Test

Assuming a successful build you are ready to test. In order to use the Xspec models you will first need to set the HEADAS environment variable:

setenv HEADAS ${CIAO}/ots/spectral

Now go back to the Sherpa page and read it carefully. Did you do all the configuration of your .sherpa.rc and matplotlibrc? OK, now try:

% ipython --pylab
import sherpa.astro.ui as ui

Note that using the --pylab switch seems to make the plotting work more reliably.

If that worked with no messages then you might be done. But the real test is fitting an X-ray spectrum (e.g. a file called acis.pi) with an Xspec model and plotting:

ui.load_pha('acis.pi')
ui.set_source(ui.xsphabs.abs1 * ui.powlaw1d.p1)
ui.fit()
ui.plot_fit_resid()

If all goes well you should see a plot. Since you are now using the matplotlib backend the ChIPS plotting commands are replaced by matplotlib commands. The first thing you might want to do is make the axes logarithmic:

ax = gca()
ax.set_xscale('log')
ax.set_yscale('log')

Debugging

If you get any messages about libraries not loading during the import sherpa.astro.ui command then something is wrong. At this top level the actual import errors are caught and replaced with more user-friendly messages. Unfortunately those messages hide what you need to know in order to debug library problems. To see what is happening you need to explicitly import libraries, e.g.:

import group
import sherpa.astro.xspec
import sherpa.astro.utils._region
import sherpa.astro.utils._wcs

If you still don't see tracebacks that indicate the problem then you probably need to edit your ~/.sherpa.rc and change the default verbosity. Here is what I have in my file:

[verbosity]
# Sherpa Chatter level
# a non-zero value will
# display full error traceback
level : 2000



    7           5