The present directory contains the following files:
- readme.1st
- integrate.c
- analytic_main.c
- analytic_jacob.c
- numeric_main.c
- numeric_jacob.c
- analytic_funct.c
- result.c
- a.dat
- output.dat
_______________________________________________________________________________
short explanation of the files:
- readme.1st:
the present document.
- integrate.c:
the package we provide: it contains the four functions:
- CalcExp
- SubStep
- IntegrationStep
- TestTolerance
- analytic_main.c:
it contains the function:
- main
a sample main for the sample problem, in the case that
the analytic expression of the Jacobian matrix is coded.
It contains the commands to include the three files:
- integrate.c
- analytic_jacob.c
- result.c
- analytic_jacob.c:
it contains the function:
- AnalyticJacob
a sample function that codes the analytic expression of
the forcing function and of its Jacobian matrix.
- numeric_main.c:
it contains the function:
- main
a sample main for the sample problem, in the case that
the analytic expression of the Jacobian matrix is not coded
but only the analytic expression of the function is coded.
It contains the commands to include the four files:
- integrate.c
- analytic_funct.c
- numeric_jacob.c
- result.c
- numeric_jacob.c
it contains the function:
- NumericJacob
a sample function that computes the numerical
central-differences estimation of the Jacobian matrix.
- analytic_funct.c:
it contains the function:
- CalcFunct
a sample function that codes the analytic expression
of the forcing function.
- result.c:
it contains the function:
- PrintResult
a sample function that outputs on file
some intermediate results.
- a.dat
the data file produced by the sample main using the PrintResult function.
- output.dat
the data file produced on the standard output by the sample main.
_______________________________________________________________________________
user guide
The package we provide is contained in the file integrate.c, and the only
function that must be called by the user is IntegrationStep, and its use
is described in detail below.
The user must:
- define the maximum problem dimension MAX_DIM
- code a C-function that computes the forcing function and its Jacobian matrix
- pass the C-function pointer as the first argument to IntegrationStep
- provide a printout function PrintResult
as explained below.
We illustrate the use of IntegrationStep to integrate a system of differential
equations, by providing two complete examples relative to the same sample
problem described in the paper (Aluffi-Pentini F, De Fonzo V, Parisi V.
A novel algorithm for the numerical integration of systems of ordinary
differential equations arising in chemical problems).
The first example shows the case in which the analytical computation of the
Jacobian matrix is coded. The complete coding of the example is contained
in the files:
- analytic_main.c
- integrate.c
- analytic_jacob.c
- result.c
The second example shows the case in which the numerical estimation of the
Jacobian matrix is coded. The complete coding of the example is contained
in the files:
- numeric_main.c
- integrate.c
- analytic_funct.c
- numeric_jacob.c
- result.c
We now explain in detail only the call sequences of IntegrationStep and
of PrintResult.
_______________________________________________________________________________
IntegrationStep:
integrates a system of differential equations from an initial point
at an initial time during a given time interval; it is an integer
function called initially by the user, and then it calls itself
recursively.
The call sequence is as follows:
int IntegrationStep
(void (funct) (double [], int, double [MAX_DIM][MAX_DIM], double []),
int dim, double t0, double h, double h_min, double h_max,
double tol_rel, double tol_abs, double x_ [], FILE* res)
The arguments of IntegrationStep are
(
void (funct): computes the forcing function and its Jacobian matrix
the arguments of (funct) are:
(
double []: input coordinates
int: number of coordinates
double [MAX_DIM][MAX_DIM]: Jacobian matrix
double []: vector forcing function
)
int dim: the dimension of the differential equation system
(i.e. the number of differential equations)
double t0: initial time
double h: time interval: in the external call (by the user)
it is the required time observation window
(in the successive recursive calls, it is iteratively
halved until it becomes the length of the accepted
time integration step, or it reaches the minimum value).
double h_min: minimum value for h in the successive calls
double h_max: maximum value for h in the successive calls
double tol_rel: relative tolerance (maximum admissible value
for the relative error)
double tol_abs: absolute tolerance (maximum admissible value
for the absolute error)
double x_ []: vector of the numerical solution value of the dependent
variable; in the external call, the input value is the
initial point of the observation window and the output
value is the final point of the solution (in the
successive recursive calls, the input value is the
initial point of the step the output value is the final
point of the step)
FILE* res: the pointer to the file where intermediate results
must be written
)
Return value:
The function returns 1 if (possibly by calling itself recursively)
the tolerance tests were OK for all the generated substeps, else returns 0
In more detail: the input argument h is the length of the step over which
the integration is to be performed (in the external call, it is
the required time observation window).
If h > h_max, the function calls itself (recursively) twice;
else it tries two consecutive steps of length h and a step of length 2h.
If the results are compatibile (with respect to the tolerance tests),
the function accepts the first step of length h and returns a value 1;
else if h/2 > h_min, the function calls itself twice to try (recursively)
two consecutive steps of length h/2;
if h/2 < h_min, the function does not call itself, returns a value 0,
and the final point x_ of the solution
is presumably inaccurate.
_______________________________________________________________________________
PrintResult
is a void function that outputs on file some intermediate results
The call sequence is as follows:
void PrintResult (int dim, double t, double x_ [], FILE* res)
The arguments of PrintResult are
(
int dim: dimension of the solution vector
double t: current time
double x_ []: current solution vector
FILE* res: pointer to output file
)
_______________________________________________________________________________