7. User Models, Statistics, and Methods Within Sherpa

It is possible for the user to create and include their own model, optimization method, and statistic function within Sherpa . Examples, which are discussed below, are provided in the sherpa_user.tar.gz file available from the Sherpa threads page. The file should be unpacked into its own directory. It contains a README file with pointers to the relevant files and directories.

7.1 User Models

The most common addition to Sherpa are user-defined models. These allow you to fit your data using your own model. There are three ways to write user models:

1. using S-Lang.

2. using a compiled language (C, C++, FORTRAN) with a S-Lang interface to Sherpa .

3. using a compiled language to interface to Sherpa .

7.1.1 Using S-Lang

User models can be written purely in S-Lang, as described in ahelp slang usermodel. This approach is recommended when the user model is not very complicated, and you do not already have a version written in a compiled language such as C, C++, or FORTRAN. It is also a good way to test out a model, since you can move to using a compiled version later on if necessary.

Advantages

• Models are quick to develop since you only need to edit a text file (no compile or linking stage is necessary).

• The model can be re-loaded without needing to re-start Sherpa , which is useful for testing and adding new features.

• Models can be given a useful name, for example you can register a model called mymodel and then use it as you would any other Sherpa model. For example

  sherpa> source = mymodel[bob]
  

• Multiple S-Lang user models can be used in the same session. So for instance you can say

  sherpa> source = mymodel1[bob] + mymodel2[fred]
  

  where mymodel1 and mymodel2 are S-Lang user models.

Disadvantages

• You have to be able to write the model in S-Lang.

• For complicated models you may be concerned about the speed of the S-Lang code.

Examples of writing 1D and 2D models in S-Lang can be found in the model_1d_noint/pure_slang_version/ and model_2d_noint/pure_slang_version/ directories.

7.1.2 Using a compiled language and S-Lang

For complicated models, where execution speed is important, or for existing models which may already be written in a compiled language, it is possible to create a S-Lang module that lets Sherpa call this model.

This is the recommended way to use compiled models from Sherpa . The alternative is to use the ascfitUserModel interface which is described in the next section.

Advantages

• Models can be given a useful name, for example you can register a model called mymodel and then use it as you would any other Sherpa model. For example

  sherpa> source = mymodel[bob]
  

• Multiple user models can be used in the same session. So for instance you can say

  sherpa> source = mymodel1[bob] + mymodel2[fred]
  

  where mymodel1 and mymodel2 are user models.

• Users do not need to tell the model how many parameters are by the model (as they do with the ascfitUserModel interface).

• The model can be called directly from the Sherpa prompt, which allows easy testing of the results.

Disadvantages

• The interface to the compiled code requires some knowledge of the S-Lang API - in particular the Intrinsic Functions section of the S-Lang Library C Programmer's Guide.

  Note that the Programmer's Guide refers to version 2 of S-Lang whereas CIAO 3.4 uses version 1.4.9. See the upgrade guide for more information on the changes between the two versions of S-Lang.

Examples of writing 1D and 2D models in a compiled language with a S-Lang interface can be found in the c_slang_version/, cc_slang_version/, and fortran_slang_version/ directories of model_1d_noint/, and model_2d_noint/.

7.1.3 Using a compiled language (the ascfitUserModel interface)

The ascfitUserModel interface is the original method provided by Sherpa for writing user models. It only allows one user model to be loaded into a Sherpa session, the model will be called usermodel, and it is used slightly differently to the other Sherpa models since users need to tell Sherpa how many model parameters there are.

The S-Lang interface is the preferred way to add compiled code as a user model, but this interface is still provided.

Advantages

• The interface requires no knowledge of S-Lang, only the language used to write the model.

Disadvantages

• Only one model can be loaded into a Sherpa session.

• The number of model parameters must be supplied by the user of the model

• It is harder to test the model from Sherpa than when the S-Lang interface is used.

Examples of writing 1D and 2D models using the ascfitUserModel interface can be found in the c_version/ and fortran_version/ directories of model_1d_noint/, and model_2d_noint/.

7.2 User Method

An optimization method contains the definition of the algorithm which is responsible for finding a minimum for the fit statistic. This is done by varying the fit parameters within their ranges. Different optimization methods use different algorithms to determine how the parameter space is searched for the minima.

The purpose of having a user-defined optimization method is to integrate your own local algorithm definition within the Sherpa fitting and modeling environment, for your own use. Unlike user models, the only way to write such a method is to use the ascfitUserMethod interface. An example method is provided in the method/ directory.

7.3 User Statistic

A fit statistic is the measure you use to compare your predicted model data to your real measured data. It is by minimizing the fit statistic that you find a good fit for your model. An example of a fit statistic is CHI GEHRELS.

The purpose of having a user defined fit statistic is to integrate your own local algorithm definition within the Sherpa fitting and modeling environment, for your own use. Unlike user models, the only way to write such a method is to use the ascfitUserStatistic interface. An example method is provided in the stat/ directory.