
Writing your own models for use in Sherpa
-----------------------------------------

There are three ways to write a model for use in Sherpa:

 1  Write the model in S-Lang

 2  Write the model in a compiled language and provide a S-Lang
    interface

 3  Write the model in a compiled language and use the
    ascfitUserModel interface

We provide examples of all three approaches for two cases:

* a 1D model (our own version of the Sherpa beta1D model)

  See the model_1d_noint/README file.

* a 2D model (our own version of the Sherpa gauss2D model)

  See the model_2d_noint/README file.

When to write the model in S-Lang?
----------------------------------

User models can be written purely in S-Lang, as described in

  ahelp slang usermodel

or

  http://cxc.harvard.edu/ciao/ahelp/slang-usermodel.html

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:

 - it is quick to write since you only need to edit a text file
   (no compile or linking stages are necessary)

 - if the model is incorrect you can edit it and re-load it 
   without having to restart Sherpa

 - 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
         source = mymodel[bob]

 - you can use more than one S-Lang user model in the same session,
   ie you can say 'source = foo1[bob] + foo2[fred]' where foo1 and
   foo2 are S_Lang user models that were registered with the
   register_model() routine (described in 'ahelp slang usermodel').

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 version


When to write the model in a compiled language with a S-Lang interface?
-----------------------------------------------------------------------

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 below.

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
         source = mymodel[bob]

 - you can use more than one S-Lang user model in the same session,
   ie you can say 'source = foo1[bob] + foo2[fred]' where foo1 and
   foo2 are S_Lang user models that were registered with the
   register_model() routine (described in 'ahelp slang usermodel').

 - users do not need to tell the model how many parameters are used
   by the model

 - you can call the model from the Sherpa prompt with known arguments
   and get back the results, which makes quick testing easier.

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" available at

     http://www.jedsoft.org/slang/doc/html/cslang-5.html#ss5.3

   Note that this document refers to version 2 of S-Lang whereas
   CIAO 3.4 uses version 1.4.9. See

     http://www.jedsoft.org/slang/doc/html/cslang-10.html#ss10.7

   for more information on the changes between versions 1 and 2 of
   S-Lang.

When to use the ascfitUserModel interface?
------------------------------------------

The ascfitUserModel is the original interface provided by Sherpa for
writing compiled 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. It is also the
only way to add user statistics and methods, although this feature
is not described in this document.

Advantages:

 - the interface requires no knowledge of S-Lang

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.
