nls2.mymodel - How to Write Programs for Evaluating nls2 Models


On to:
DESCRIPTION
LIST OF THE PROGRAMS REQUIRED
ROLES OF THE PROGRAMS
SYNTAX
ARGUMENTS
VALUE
OVERFLOW PROTECTION
FORTRAN PROGRAMS
REFERENCES
SEE-ALSO





DESCRIPTION:

This entry explains how to write manually programs that calculate models studied by function `nls2'.

The non-linear regression function `nls2' evaluates the model either by syntax trees - which are built from the model description-file (see `nls2.model') -, or by C or Fortran programs.
Source files can be generated automatically: see `loadnls2'. They can also be provided by the user. Here are described the conventions that must be respected in that case.


Sommaire

LIST OF THE PROGRAMS REQUIRED:

Five programs are required: "calcf_", "calcv_", "calcphi_","calcodes_" and "calcjac_". According to the type of model, only some of them are actually used; the others must exist but may be empty.


ROLES OF THE PROGRAMS:

"calcf_" calculates the regression function and its derivatives with respect to the parameters, for one curve. "calcf_" is used when the model is not described by a differential equations system.

"calcv_" calculates the variance function and its derivatives with respect to the parameters, for one curve. "calcv_" is used when a variance function is declared in the model description-file.

"calcphi_" is used when the model is described by a differential equations system. It calculates the regression function and its derivatives, on given values of the system and of its derivatives, for one curve.

"calcodes_" is used when the model is described by a differential equations system; it calculates the system, the regression function, and their derivatives, for one value of the independent variables.

"calcjac_" calculates the values of the jacobian when the model is described by a differential equations system. In the current version, this program must exist but it is not used.


Sommaire

SYNTAX:

short int calcf_(pbase, nbgamf, nbobsc, m, theta, gamf, x, f, df, le, ie)
/* input arguments */
short int pbase, nbgamf, nbobsc, m;
double *theta, *gamf, **x;
/* output arguments */
double *f, **df;
short int *le, *ie;

short int calcv_(pbase, qbase, nbgamv, nbobsc, m, theta, beta, gamv, f, df, x, v, dthetav, dbetav, le, ie)
/* input arguments */
short int pbase, qbase, nbgamv, nbobsc, m;
double *theta, *beta, *gamv, *f, **df, **x;
/* output arguments */
double *v, **dthetav, **dbetav;
short int *le, *ie;

short int calcphi_(pbase, nbgamf, nbobsc, m, theta, gamf, x, FOdes, dFOdes, f, df, le, ie)
/* input arguments */
short int pbase, nbgamf, nbobsc, m;
double *theta, *gamf, **x;
/* output arguments */
double ***FOdes, ***dFOdes, *f, **df;
short int *le, *ie;

short int calcodes_(neq, t, y, ydot)
/* input arguments */
int *neq;
double *t;
/* in-output arguments */
double *y, *ydot;

calcjac_() {}

Sommaire




ARGUMENTS:

pbase
number of parameters that appear in the regression function (the regression basic parameters).
qbase
number of parameters that appear in the variance function and not in the regression function (the variance basic parameters).
nbgamf
number of second level parameters in the regression function (parameters that will not be estimated but are set to a known value).
nbgamv
number of second level parameters in the variance function.
nbobsc
number of observations for the current curve, replications not included if any.
m
number of independent variables.
theta
values of the regression parameters for the current curve: "pbase" values.
beta
values of the variance parameters for the current curve: "qbase" values.
gamf
values of the second level parameters of the regression function: "nbgamf" values.
gamv
values of the second level parameters of the variance function: "nbgamv" values.
x
values of the independent variables for the current curve: "nbobsc*m" values sorted on observations first.
f
values of the regression function for the current curve: "nbobsc" values.
df
values of the derivatives of the regression function with respect to its parameters: "nbobsc*pbase" values, sorted on observations first.

Sommaire

v
values of the variance function: "nbobsc" values.
dthetav
values of the derivatives of the variance function with respect to the parameters that appear in the regression function: "nbobsc*pbase" values, sorted on observations first.
dbetav
values of the derivatives of the variance function with respect to the parameters that appear in the variance function only: "nbobsc*qbase" values, sorted on observations first.
FOdes
values of the integrated system for the current curve: "nbobsc*nbj*nbeq" values where "nbj" is the number of integration values and "nbeq" is the number of equations in the model description. The values should be sorted on "nbobsc" first, then on "nbj", and finally on "nbeq".
dFOdes
values of the derivatives of the integrated system with respect to the parameters, - parameters that are initial conditions included, if any - for the current curve; "nbobsc*nbj*nbs" values where "nbj" is the number of integration values and "nbs" is the length of the complete system to be integrated minus the number of equations in the model description. The values should be sorted on "nbobsc" first, then on "nbj", and finally on "nbs".
neq
a vector that contains in that order: "nbsys,pbase,nbgamf,i,nbobsc,m,code", where:
- "nbsys" is the number of equations solved by the integration system,
- "pbase,nbgamf,nbobsc,m": see above,
- "i" is the index of the current observation inside the current curve,
- "code" is an output: if an error occurs, it should be equal to 150 (a conventional error code). Otherwise, it should be null.

Sommaire

t
the values of the integration variable for the current curve.
le
when an error occurs, indicates whether this happens when calculating "f" (then "le" should be equal to 1), "v" (le=2), "df" (le=3), "dthetav" (le=4), "dbetav" (le=5), or when calculating auxiliary variables (le=6).
ie
when an error occurs, the index of the observation in the current curve (from 1) where the error happens.
y
vector that contains (in the order indicated):
- the values of the system equations ("nbsys" values: see the argument `neq'),
- the values of the regression parameters,
- the values of the independent variables for the current curve (all the values of the first variable, then all values of the second variable, etc.
ydot
the derivatives of the system equations with respect to the integration variable ("nbsys" values: see the argument `neq').

Sommaire


VALUE:

All these programs return the value 0 if no error occurs and the value 150 (a conventional error code) otherwise.


OVERFLOW PROTECTION:

Protection against overflows and divisions by zero are ensured by using the following C-functions: mylog(x) (instead of log10), myln(x) (=log), mypow(x, y) (=x**y), mydiv(x, y) (=x/y) , myexp(x) (=exp).
The type of the arguments and the returned value is "double".
To use these functions, you should insert the following sentences at the beginning of your C source-file:
#include <stdio.h>
#include <math.h>
#include "nltypes.h"
#include "nlcodes.h"
#include "nlmacros.h"
#include "nlfonc.h"

Sommaire




FORTRAN PROGRAMS:

In the case of Fortran programs, the program names should be "mycalcf", "mycalcv", "mycalcphi","mycalcodes" and "mycalcjac" (without underscore at the ends of the names).

Type "double" corresponds to "double precision" and "short int" to "integer".


REFERENCES:

`nls2 Reference Manual'.


SEE ALSO:

`nls2', `loadnls2'

Sommaire


Creation: 09/12/2001 -