source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/cvodes/cvodes_bandpre.h @ 16222

Last change on this file since 16222 was 16222, checked in by gkronber, 4 years ago

#2925:

  • added comments about parameter identification for differential equation models
  • added source code of cvodes library (part of sundials) which provides functionality to calculate gradients for the parameters of partial differential equation models efficiently using the 'adjoint state method'.
  • added compiled version of cvodes
File size: 7.1 KB
Line 
1/*
2 * -----------------------------------------------------------------
3 * Programmer(s): Daniel R. Reynolds @ SMU
4 *                Radu Serban @ LLNL
5 * -----------------------------------------------------------------
6 * LLNS/SMU Copyright Start
7 * Copyright (c) 2017, Southern Methodist University and
8 * Lawrence Livermore National Security
9 *
10 * This work was performed under the auspices of the U.S. Department
11 * of Energy by Southern Methodist University and Lawrence Livermore
12 * National Laboratory under Contract DE-AC52-07NA27344.
13 * Produced at Southern Methodist University and the Lawrence
14 * Livermore National Laboratory.
15 *
16 * All rights reserved.
17 * For details, see the LICENSE file.
18 * LLNS/SMU Copyright End
19 * -----------------------------------------------------------------
20 * This is the header file for the CVSBANDPRE module, which
21 * provides a banded difference quotient Jacobian-based
22 * preconditioner and solver routines for use with the CVSSPILS
23 * iterative linear solver interface.
24 *
25 * Part I contains type definitions and function prototypes for using
26 * CVSBANDPRE on forward problems (IVP integration and/or FSA)
27 *
28 * Part II contains type definitions and function prototypes for using
29 * CVSBANDPRE on adjopint (backward) problems
30 * -----------------------------------------------------------------
31 */
32
33#ifndef _CVSBANDPRE_H
34#define _CVSBANDPRE_H
35
36#include <sundials/sundials_nvector.h>
37
38#ifdef __cplusplus  /* wrapper to enable C++ usage */
39extern "C" {
40#endif
41
42/*=================================================================
43  PART I - forward problems
44  =================================================================*/
45
46/*-----------------------------------------------------------------
47  SUMMARY
48 
49  These routines provide a band matrix preconditioner based on
50  difference quotients of the ODE right-hand side function f.
51  The user supplies parameters
52    mu = upper half-bandwidth (number of super-diagonals)
53    ml = lower half-bandwidth (number of sub-diagonals)
54  The routines generate a band matrix of bandwidth ml + mu + 1
55  and use this to form a preconditioner for use with the Krylov
56  linear solver through the CVSPILS interface. Although this
57  matrix is intended to approximate the Jacobian df/dy, it may
58  be a very crude approximation. The true Jacobian need not be
59  banded, or its true bandwith may be larger than ml + mu + 1,
60  as long as the banded approximation generated here is
61  sufficiently accurate to speed convergence as a preconditioner.
62 
63  Usage:
64    The following is a summary of the usage of this module.
65    Details of the calls to CVodeCreate, CVodeInit, CVSp*,
66    and CVode are available in the User Guide.
67    To use these routines, the sequence of calls in the user
68    main program should be as follows:
69 
70    #include <cvodes/cvodes_bandpre.h>
71    #include <nvector_serial.h>   (or openmp or pthreads)
72    ...
73    void *cvode_mem;
74    ...
75    Set y0
76    ...
77    SUNLinearSolver LS = SUNSPBCGS(y0, pretype, maxl);
78      -or-
79    SUNLinearSolver LS = SUNSPFGMR(y0, pretype, maxl);
80      -or-
81    SUNLinearSolver LS = SUNSPGMR(y0, pretype, maxl);
82      -or-
83    SUNLinearSolver LS = SUNSPTFQMR(y0, pretype, maxl);
84      -or-
85    SUNLinearSolver LS = SUNPCG(y0, pretype, maxl);
86    ...
87    cvode_mem = CVodeCreate(...);
88    flag = CVodeInit(...);
89    ...
90    flag = CVSpilsSetLinearSolver(cvode_mem, LS);
91    ...
92    flag = CVBandPrecInit(cvode_mem, N, mu, ml);
93    ...
94    flag = CVode(...);
95    ...
96    Free y0
97    ...
98    CVodeFree(&cvode_mem);
99    ...
100    SUNLinSolFree(LS);
101    ...
102 
103  Notes:
104  (1) Include this file for the CVBandPrecData type definition.
105  (2) In the CVBandPrecInit call, the arguments N is the
106      problem dimension.
107  (3) In the linear solver creation call, the user is free to
108      specify the input pretype and the optional input maxl.
109  -----------------------------------------------------------------*/
110
111
112/*-----------------------------------------------------------------
113  Function : CVBandPrecInit
114  -----------------------------------------------------------------
115  CVBandPrecInit allocates and initializes the BANDPRE preconditioner
116  module. This function must be called AFTER the CVSPILS linear
117  solver interface has been created.
118 
119  The parameters of CVBandPrecInit are as follows:
120 
121  cvode_mem is the pointer to CVODE memory returned by CVodeCreate.
122 
123  N is the problem size.
124 
125  mu is the upper half bandwidth.
126 
127  ml is the lower half bandwidth.
128 
129  The return value of CVBandPrecInit is one of:
130    CVSPILS_SUCCESS if no errors occurred
131    CVSPILS_MEM_NULL if the integrator memory is NULL
132    CVSPILS_LMEM_NULL if the linear solver memory is NULL
133    CVSPILS_ILL_INPUT if an input has an illegal value
134    CVSPILS_MEM_FAIL if a memory allocation request failed
135 
136  NOTE: The band preconditioner assumes a serial/OpenMP/Pthreads
137        implementation of the NVECTOR package. Therefore,
138        CVBandPrecInit will first test for a compatible N_Vector
139        internal representation by checking for required functions.
140  -----------------------------------------------------------------*/
141SUNDIALS_EXPORT int CVBandPrecInit(void *cvode_mem, sunindextype N,
142                                   sunindextype mu, sunindextype ml);
143
144/*-----------------------------------------------------------------
145  Optional output functions : CVBandPrecGet*
146  -----------------------------------------------------------------
147  CVBandPrecGetWorkSpace returns the real and integer work space used
148                         by CVBANDPRE.
149  CVBandPrecGetNumRhsEvals returns the number of calls made from
150                           CVBANDPRE to the user's right-hand side
151                           routine f.
152 
153  The return value of CVBandPrecGet* is one of:
154    CVSPILS_SUCCESS if no errors occurred
155    CVSPILS_MEM_NULL if the integrator memory is NULL
156    CVSPILS_LMEM_NULL if the linear solver memory is NULL
157    CVSPILS_PMEM_NULL if the preconditioner memory is NULL
158  -----------------------------------------------------------------*/
159SUNDIALS_EXPORT int CVBandPrecGetWorkSpace(void *cvode_mem,
160                                           long int *lenrwLS,
161                                           long int *leniwLS);
162SUNDIALS_EXPORT int CVBandPrecGetNumRhsEvals(void *cvode_mem,
163                                             long int *nfevalsBP);
164
165
166/*=================================================================
167  PART II - backward problems
168  =================================================================*/
169
170/*-----------------------------------------------------------------
171  Functions: CVBandPrecInitB
172  -----------------------------------------------------------------
173  Interface functions for the CVBANDPRE preconditioner to be used
174  on the backward phase.
175 
176  CVBandPrecInitB interfaces to the CVBANDPRE preconditioner
177  for the backward integration.
178  The 'which' argument is the int returned by CVodeCreateB.
179  -----------------------------------------------------------------*/
180SUNDIALS_EXPORT int CVBandPrecInitB(void *cvode_mem, int which,
181                                    sunindextype nB, sunindextype muB,
182                                    sunindextype mlB);
183
184#ifdef __cplusplus
185}
186#endif
187
188#endif
Note: See TracBrowser for help on using the repository browser.