= Creating New Models in Sansview =

This document provides an introduction for creating new scattering models in the software Sansview. For the project homepage visit http://sourceforge.net/projects/sansviewproject/


== Architecture ==

Most of Sansview including the GUI, plotting and fitting functions is written in python. Due to well known performance issues it makes sense to write any models involved in heavy computation in a faster language, here both C and C++. In sansview the interface between the Python and C++ is done with the ctypes library, though in practice we hardly need to deal with this.


== Writing your C++ Model ==

Here we discuss only the basics of getting a model to work; for a more detailed tutorial on computation of form factors see the sans toolbox at http://www.ncnr.nist.gov/staff/hammouda/the_SANS_toolbox.pdf or many other good online tutorials.

To begin writing the model, check out the project trunk on subversion using the link to sourceforge at the top of the page. Assuming you install it into your home directory ~/ (which in practice is a bad idea), check the project builds okay by running

	{{{~/$ sudo python setup.py install}}}

To check this has worked worked, or indeed at any time run your own version of sansview do

	{{{~/$ python sansview/sansview.py}}}

Our C++ model takes the form of a class that naturally has a a header file and body. Here we call our model testModel that correspondingly has testModel.h and ''testModel.cpp''. We place the header file in ~/sansmodels/include/ and the source file in ~/sansmodels/src/c_models/ . 

We begin with the preprocessor directives for ''testModel.h''. The usual #ifndef....#define....#endif are of course required as usual for header files.

{{{#include "parameters.hh"}}}

Parameters.hh holds the class definition for the Parameter class, the basic representation of any parameter in your form factor. We then fill out a few lines of commented code that are required by the wrapper class to understand what your model does.
{{{
//[PYTHONCLASS] = testModel
//[DISP_PARAMS] = myparam
//[DESCRIPTION] =<text> test class for sansview </text>
}}}

PYTHONCLASS and DESCRIPTION are both self explanatory. The DISP_PARAMS section should include a list of the parameters your model uses. Here we define one – myparam.

Next comes the class declaration itself.

{{{
class testModel {

public:
  Parameter myparam;

  testModel();

  // Operators to get I(Q)
  double operator()(double q);
  double operator()(double qx,double qy);

  double evaluate_rphi(double q, double phi);
  double calculate_ER();
  double calculate_VR();

};

}}}

As you will see we have the declaration of our parameter, followed by the constructor. Next are the 5 methods required by the wrapper function in order to generate a proper model. The first two operators represent the one and two dimensional form factor functions respectively. Next come the methods for evaluating the rphi function and calculating the effective radius.

Next onto ''testModel.cpp'' implementing these functions. First of course comes the includes (don't forget ''testModel.h''.

{{{

#include <math.h>
#include "parameters.hh"
#include "testModel.h"
}}}

''Math.h'' is of course an optional import but is pretty necessary for most form factor calculations. 

Then we get on to the body of the functions which is implemented in the most trivial way possible.

{{{
testModel::testModel() {
  myparam = Parameter(1.0);
}
double testModel::operator()(double q) {
  return 1.0;
}
double testModel::operator()(double qx, double qy) {
  return 1.0;
}

double testModel::evaluate_rphi(double q, double phi) {
  return 1.0;
}

double testModel::calculate_ER() {
  return 1.0;
}

double testModel::calculate_VR() {
  return 1.0;
}

}}}

Now we have all the code we need to create a flat line across our screen at 1.0 in the model plot.


== Incorporating your Model in Sansview ==


The wrapper for python will create 3 separate chunks of code –''CtestModel.cpp, CtestModel.py and testModel.py''– this being what is actually called from Sansview. Make sure your ''testModel.cpp'' is placed correctly in sansmodels/src/c_models/ and the Sansview installation process will pick it up and do all the wrapping automatically. 

Next, head over to the file

	fittingview/src/sans/perspectives/fitting/models.py

This is where the model is actually added to the selection list for modelling and gui. In the class ModelManagerBase exists a method called _getModelList. In the relevant part of the method (you will easily see where) add

{{{
from sans.models.testModel import testModel
self.shape_list.append(testModel)
self.model_name_list.append(testModel.__name__)
}}}

And that's it! A model called testModel should appear in the drop down menu in fittingview under 'Shapes'. Change the middle line above suitably if you would prefer it to appear under a different category.