Installing a New Model

We will illustrate the procedure of installing a new model by using a concrete example. Suppose that you are interested in studying the level sets of the planar variety defined by the zero set of the function
x^3 - xy + alpha + beta y

To install this function into Pisces:

Create a template file

Copy a preexisting model file or download and save Pisces' model template file.
For example: save the template file as template_def.c

Edit the template file

This step involves typing in the equation for the function whose level sets are of interest, and completing a series of "administrative tasks" such as naming your variables and parameters, and giving default interval ranges for each variable and parameter.
For example:

• Using a text editor, name your function "Template".
  #define MODEL_NAME Template
  
• Define your function in C-syntax. For each function evaluation, the current values of your variables will be stored in the C variables x[0], x[1],.... The current values of your parameters will be stored in the C variables p[0], p[1],..., and the value of your function evaluated at a point should be stored in f[0], f[1],.... For example, the cubic polynomial presented above would be defined as
  f[0]=x[0]*x[0]*x[0] -x[0]*x[1] +p[0] +p[1]*x[1];
• Define a Jacobian. This step is optional, but is recommended when using Pisces for research or when studying functions with singularities or large derivatives. If you want Pisces to use an analytic Jacobian, follow the instructions provided in the template file.
• Define the model's domain, parameter space, and range space. Each line has the form
  {"x", -0.95, -1.0, 1.0}
  where x is the name of a variable you are defining, -0.95 is its initial value, and [-1,1] is the default domain for computations and graphics involving the x variable.
• Tell Pisces whether the function is a polynomial, and, if so, what is its degree.

Add your model to the Pisces model menu

Edit the file model_config.c to add a line of the form
DEFINE_MODEL( Template, "My First Model", "2D");
The first entry is the name of the model that you indicated in the MODEL_NAME macro of the template file. The second entry is a string that will appear on the Pisces menu of installed models. The third string determines a model "subclass." Subclasses are not yet implemented.

Add the name of your template file to the Makefile

Edit the file Makefile and add the line
SRCS= model_config.c template_def.c
after the initial set of comment lines.

Compile and link your code with the standard Pisces libraries

This only requires that you type make pisces, and then subsequently invoke the executable ./pisces whenever you want to use the model that you installed.