Installation

Requirements

Sherpa has the following requirements:

  • Python 2.7, 3.5, or 3.6
  • NumPy (the exact lower limit has not been determined, but it is likely to be 1.7.0 or later)
  • Linux or OS-X (patches to add Windows support are welcome)

Sherpa can take advantage of the following Python packages if installed:

  • astropy: for reading and writing files in FITS format.
  • matplotlib: for visualisation of one-dimensional data or models, one- or two- dimensional error analysis, and the results of Monte-Carlo Markov Chain runs.

The Sherpa build can be configured to create the sherpa.astro.xspec module, which provides the models and utility functions from the XSPEC. The supported versions of XSPEC are 12.8 and 12.9, but it is strongly suggested that version 12.9 be used.

Interactive display and manipulation of two-dimensional images is available if the DS9 image viewer is installed.

Releases and version numbers

The Sherpa release policy has a major release at the start of the year, corresponding to the code that is released in the previous December as part of the CIAO release, followed by several smaller releases throughout the year.

Information on the Sherpa releases is available from the Zenodo page for Sherpa, using the Digital Object Identifier (DOI) 10.5281/zenodo.593753.

What version of Sherpa is installed?

The version number and git commit id of Sherpa can be retrieved from the sherpa._version module using the following command:

python -c 'import sherpa._version; print(sherpa._version.get_versions())'
{'full': '8638ca0fe411693ea3b1eebe0df47512ec5bd542', 'version': '4.9.0'}

Citing Sherpa

Information on citing Sherpa can be found from the CITATION document in the Sherpa repository, or from the Sherpa Zenodo page.

Installing a pre-compiled version of Sherpa

Additional useful Python packages include astropy, matplotlib, and ipython-notebook.

Using the Anaconda python distribution

The Chandra X-ray Center provides releases of Sherpa that can be installed using Anaconda from the sherpa channel. First check to see what the latest available version is by using:

conda install -c sherpa sherpa --dry-run

and then, if there is a version available and there are no significant upgrades to the dependencies, Sherpa can be installed using:

conda install -c sherpa sherpa

It is strongly suggested that Sherpa is installed into a named conda environment (i.e. not the default environment).

Using pip

Sherpa is also available from PyPI at https://pypi.python.org/pypi/sherpa and can be installed with the command:

pip install sherpa

The NumPy package must already have been installed for this to work.

Building from source

Prerequisites

The prerequisites for building from source are:

  • Python versions: 2.7, 3.5, 3.6
  • Python packages: setuptools, numpy
  • System: gcc, g++, gfortran, make, flex, bison (the aim is to support recent versions of these tools; please report problems to the Sherpa issue tracker).

It is highly recommended that matplotlib and astropy be installed before building Sherpa, to avoid skipping a number of tests in the test suite.

The full Sherpa test suite requires the mock package (Python 2.7 only) and pytest. These packages should be installed automatically for you by the test suite if they do not already exist.

If DS9 is installed, along with the XPA commands, then the Sherpa test suite will cause multiple instances of DS9 to appear and then disappear, almost immediately. To avoid this disruption, install of both the pytest-xvfb package and the X virtual frame buffer (Xvfb), which will cause the DS9 tests to use the virtual framebuffer rather than the existing X session for display.

Obtaining the source package

The source code can be obtained as a release package from Zenodo - e.g. the CIAO 4.9 release - or from the Sherpa repository on GitHub, either a release version, such as the ciao4.9 tag, or the master branch , which is not guaranteed to be stable.

For example:

git clone git://github.com/sherpa/sherpa.git
cd sherpa
git checkout ciao4.9

will use the ciao4.9 tag.

Configuring the build

The Sherpa build is controlled by the setup.cfg file in the root of the Sherpa source tree. These configuration options include:

FFTW

Sherpa ships with the fftw library source code and builds it by default. To use a different version, change the fftw options in the sherpa_config section of the setup.cfg file. The options to change are:

fftw=local
fftw-include_dirs=/usr/local/include
fftw-lib-dirs=/use/local/lib
fftw-libraries=fftw3

The fftw option must be set to local and then the remaining options changed to match the location of the local installation.

XSPEC

Sherpa does not build support for XSPEC models by default. This can be changed by options in the xspec_config section of the setup.cfg file:

with-xspec=True
xspec_lib_dirs=None
xspec_libraries=XSFunctions XSModel XSUtil XS
cfitsio_lib_dirs=None
cfitsio_libraries=cfitsio
ccfits_lib_dirs=None
ccfits_libraries=CCfits
wcslib_lib_dirs=None
wcslib_libraries=wcs
gfortran_lib_dirs=None
gfortran_libraries=gfortran

The with-xspec option must be set to True and then the remaining options set based on whether just the XSPEC model library or the full XSPEC system has been installed.

  1. If the full XSPEC system has been built then use:

    xspec_lib_dirs=$HEADAS/lib
ccfits_libraries=CCfits_2.5
wcslib_libraries=wcs-5.16

    The $HEADAS environment variable should be replaced by the location of XSPEC. These values are for XSPEC 12.9.1 using a Linux system and may need adjusting for other releases or operating systems (in particular the version numbers of the libraries, such as cfitsio).

  2. If the model-only build of XSPEC has been installed, then the configuration is similar, but the library names may not need version numbers and locations, depending on how the cfistio, CCfits, and wcs libraries were installed

A common problem is to set the xspec_lib_dirs option to the value of $HEADAS instead of $HEADAS/lib. This will cause the build to fail with errors about being unable to find the various XSPEC libraries, such as XSFunctions and XSModel.

The gfortran options should be adjusted if there are problems building or using the XSPEC module.

The current supported versions of XSPEC are 12.8.2, 12.9.0, and 12.9.1 (although not all models in the later versions are currently available); it is strongly recommended that version 12.9 be used in preference to 12.8.2.

In order for the XSPEC module to be used from Python, the HEADAS environment variable must be set before the sherpa.astro.xspec module is imported.

The Sherpa test suite includes an extensive set of tests of this module, but a quick check of an installed version can be done with the following:

>>> from sherpa.astro import xspec
>>> xspec.get_xsversion()
'12.9.1n'

Other options

The remaining options in the setup.cfg file allow Sherpa to be built in specific environments, such as when it is built as part of the CIAO analysis system. Please see the comments in the setup.cfg file for more information on these options.

Building and Installing

Note

It is highly recommended that some form of virtual environment, such as a conda environment or that provided by Virtualenv, be used when building and installing Sherpa.

A standard installation

From the root of the Sherpa source tree, Sherpa can be built by saying:

python setup.py build

and installed with one of:

python setup.py install
python setup.py install --user

A development build

The develop option should be used when developing Sherpa (such as adding new functionality or fixing a bug):

python setup.py develop

Tests can then be run with the test option:

python setup.py test

The Sherpa test data suite can be installed to reduce the number of tests that are skipped with the following (this is only for those builds which used git to access the source code):

git submodule init
git submodule update

Note

Although the standard Python setuptools approach is used to build Sherpa, there may be issues when using some of the other build targets, such as build_ext. Please report these to the Sherpa issues page.

Building the documentation

Warning

The documentation support is highly experimental. It appears that you may have to have run python setup.py develop first, which is annoying.

Building the documentation requires the Sherpa source code and several additional packages:

  • Sphinx: probably best to stick to version 1.3 or later
  • The sphinx_rtd_theme
  • mock if using Python 2.7

With these installed, the documentation can be built with the build_sphinx target:

python setup.py build_sphinx

The documentation should be placed in build/sphinx/html/index.html, although this may depend on what version of Sphinx is used.

At present there is only support for building the HTML format of the documentation.

Testing the Sherpa installation

A very-brief “smoke” test can be run from the command-line with the sherpa_smoke executable:

sherpa_smoke
WARNING: failed to import sherpa.astro.xspec; XSPEC models will not be available
----------------------------------------------------------------------
Ran 7 tests in 0.456s

OK (skipped=5)

or from the Python prompt:

>>> import sherpa
>>> sherpa.smoke()
WARNING: failed to import sherpa.astro.xspec; XSPEC models will not be available
----------------------------------------------------------------------
Ran 7 tests in 0.447s

OK (skipped=5)

This provides basic validation that Sherpa has been installed correctly, but does not run many functional tests. The screen output will include additional warning messages if the astropy or matplotlib packages are not installed, or Sherpa was built without support for the XSPEC model library.

The Sherpa installation also includes the sherpa_test command-line tool which will run through the Sherpa test suite (the number of tests depends on what optional packages are available and how Sherpa was configured when built):

sherpa_test

The sherpa Anaconda channel contains the sherpatest package, which provides a number of data files in ASCII and FITS formats. This is only useful when developing Sherpa, since the package is large. It will automatically be picked up by the sherpa_test script once it is installed.