Last modified: December 2020

AHELP for CIAO 4.13 Sherpa v1


Context: sherpa


The .sherpa.rc file provides user-configuration options for Sherpa


When Sherpa is started, it processes the $HOME/.sherpa.rc resource file. The resource file defines default behavior for the Sherpa commands and can be customized to the user's preferences.

The .sherpa.rc file may be edited in any text editor to change the settings.

Contents of default .sherpa.rc file

The default .sherpa.rc file contains the following entries:

# Plotting packages available- pylab
plot_pkg   : pylab

# IO packages available- pyfits, crates
io_pkg     : crates

# If true, use truncation value in Cash, C-stat
truncate   : True

# Truncation value for Cash, C-stat (ignored if
# truncate option is False)
trunc_value: 1.0e-25

# The value used to replace energy bin edges (the ENERG_LO column) in
# ARF and RMF files which are set to 0? The field can either be "None" -
# in which case no replacement is made but an error is raised - or replaced
# by this value, which must be a float greater than 0 (and is in keV).
minimum_energy: 1.0e-10

# Sherpa Chatter level
# a non-zero value will
# display full error traceback
# This option is only used by Sherpa up to version 4.10.1
level      : 0
# NumPy arrays have a threshold size print option, such that when an
# array greater than that size is converted to a string, for printing,
# only the first few and last few elements are shown.  If the array is
# smaller than the threshold size, all the elements are printed out.
# (This setting makes no change to the actual array, but merely
# governs how the array is represented when a copy of the array is
# converted to a string.)
# The default threshold size is 1000.  Here, the threshold size is
# changed to a much larger value as Sherpa often deals with large
# arrays.
arraylength: 1000000

# Integral number of cores to use for all parallel operations
# 'None' indicates that all available cores will be used.
# Fewer than 2 will turn off parallel processing.
numcores : None

# Define the method by which the multiprocessing package starts
# parallel processes. Sherpa requires the "fork" method in order to
# utilize multiprocessing to improve performance and pass all tests.
# However, on MacOSX there are known issues with using "fork" that
# prompted a change in the multiprocessing default to be "spawn" on
# MacOSX. Expert users may consider changing this value to either
# "spawn" or "default", where the latter will use the
# platform-specific start method of the multiprocessing package.
multiprocessing_start_method: fork



The plot_pkg line should now (as of CIAO 4.12) be set to pylab since chips is no-longer supported.


The io_pkg defines whether crates (the default) or AstroPy (pyfits) will be used to handle reading and writing of files. CRATES is a software package developed by the CXC and distributed in CIAO; see "ahelp crates" for details. The AstroPy package can be installed into CIAO using the 'pip3' command provided with CIAO - e.g.

unix% pip3 install astropy

or with conda, if the conda version of CIAO is installed:

unix% conda install astropy

Note that the choice of pyfits for I/O will mean that CIAO Data Model syntax (such as on the fly filtering, column selection, and binning) can not be used.


truncate and trunc_value

The Cash and C-stat statistic functions evaluate the logarithm of each data point. If the number of counts is zero or negative, it's not possible to take the log of that number.

If truncate is set to True (the default), then log(<trunc_value>) is substituted into the equation, and the statistics calculation proceeds. The default trunc_value is 1.0e-25.

If truncate is set to False, C-stat or Cash returns an error and stops the calculation when the number of counts in a bin is zero or negative. The trunc_value setting is not used.



The value used to replace the minimum energy value of ARF and RMF values that are invalid (i.e. are set to 0).



When a NumPy array is converted to a string for printing to the screen, only the first few and last few elements are shown. The arraylength value determines only how the array is displayed; it does not affect the the actual array. The default value is 1000000, as Sherpa often deals with large arrays.


This option is no-longer used by Sherpa and is only kept for backwards compatibility.


The 'numcores' switch in the [parallel] section is available for setting the number of cores on the user's system which should be used in the execution of the Sherpa parallelized commands, such as the computationally intensive conf() and proj() functions. The default value for 'numcores' is None, which indicates that all available cores will be used for concurrent functions.


The 'multiprocessing_start_method' setting was added to support changes in the multiprocessing module on MacOS in Python 3.8. Please contact the CXC Helpdesk if you find you need to change this setting.

Changes in CIAO 4.13


The multiprocessing section is new.

Changes in CIAO 4.12


The CIAO 4.12 release no-long includes ChIPS, so the plot_pkg setting has been changed to pylab. Sherpa will automatically switch to pylab if it finds a configuration file containing chips, but will warn you about it.


See the bugs pages on the Sherpa website for an up-to-date listing of known bugs.