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.
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.
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_()
{}
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.
- 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.
- 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').
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"
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'
Creation: 09/12/2001 -