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 ) _______________________________________________________________________________