Free cookie consent management tool by TermsFeed Policy Generator

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

Last change on this file since 16222 was 16222, checked in by gkronber, 5 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 Reynolds @ SMU
4 *                David Gardner, Carol Woodward, Slaven Peles @ 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 a generic matrix package.
21 * It defines the SUNMatrix structure (_generic_SUNMatrix) which
22 * contains the following fields:
23 *   - an implementation-dependent 'content' field which contains
24 *     the description and actual data of the matrix
25 *   - an 'ops' filed which contains a structure listing operations
26 *     acting on such matrices
27 *
28 * Part I of this file contains enumeration constants for all
29 * SUNDIALS-defined matrix types, as well as a generic type for
30 * user-supplied matrix types.
31 *
32 * Part II of this file contains type declarations for the
33 * _generic_SUNMatrix and _generic_SUNMatrix_Ops structures, as well
34 * as references to pointers to such structures (SUNMatrix).
35 *
36 * Part III of this file contains the prototypes for the matrix
37 * functions which operate on SUNMatrix.
38 *
39 * At a minimum, a particular implementation of a SUNMatrix must
40 * do the following:
41 *  - specify the 'content' field of SUNMatrix,
42 *  - implement the operations on those SUNMatrix,
43 *  - provide a constructor routine for new SUNMatrix objects
44 *
45 * Additionally, a SUNMatrix implementation may provide the following:
46 *  - macros to access the underlying SUNMatrix data
47 *  - a routine to print the content of a SUNMatrix
48 * -----------------------------------------------------------------
49 */
50
51#ifndef _SUNMATRIX_H
52#define _SUNMATRIX_H
53 
54#include <sundials/sundials_types.h>
55#include <sundials/sundials_nvector.h>
56
57#ifdef __cplusplus  /* wrapper to enable C++ usage */
58extern "C" {
59#endif
60 
61 
62/*
63 * -----------------------------------------------------------------
64 * I. Implemented SUNMatrix types
65 * -----------------------------------------------------------------
66 */
67 
68typedef enum {
69  SUNMATRIX_DENSE,
70  SUNMATRIX_BAND,
71  SUNMATRIX_SPARSE,
72  SUNMATRIX_CUSTOM
73} SUNMatrix_ID;
74
75 
76/*
77 * -----------------------------------------------------------------
78 * II. Generic definition of SUNMatrix
79 * -----------------------------------------------------------------
80 */
81 
82/* Forward reference for pointer to SUNMatrix_Ops object */
83typedef struct _generic_SUNMatrix_Ops *SUNMatrix_Ops;
84 
85/* Forward reference for pointer to SUNMatrix object */
86typedef struct _generic_SUNMatrix *SUNMatrix;
87 
88/* Structure containing function pointers to matrix operations  */ 
89struct _generic_SUNMatrix_Ops {
90  SUNMatrix_ID (*getid)(SUNMatrix);
91  SUNMatrix    (*clone)(SUNMatrix);
92  void         (*destroy)(SUNMatrix);
93  int          (*zero)(SUNMatrix);
94  int          (*copy)(SUNMatrix, SUNMatrix);
95  int          (*scaleadd)(realtype, SUNMatrix, SUNMatrix);
96  int          (*scaleaddi)(realtype, SUNMatrix);
97  int          (*matvec)(SUNMatrix, N_Vector, N_Vector);
98  int          (*space)(SUNMatrix, long int*, long int*);
99};
100 
101/* A matrix is a structure with an implementation-dependent
102   'content' field, and a pointer to a structure of matrix
103   operations corresponding to that implementation.  */
104struct _generic_SUNMatrix {
105  void *content;
106  struct _generic_SUNMatrix_Ops *ops;
107};
108
109 
110/*
111 * -----------------------------------------------------------------
112 * III. Functions exported by SUNMatrix module
113 *
114 * SUNMatGetID
115 *   Returns an identifier for the matrix type from the enumeration
116 *   SUNMatrix_ID.  This will be queried by a given linear solver to
117 *   assess compatibility.
118 *
119 * SUNMatClone
120 *   Creates a new matrix of the same type as an existing matrix.
121 *   It does not copy the matrix, but rather allocates storage for
122 *   the new matrix.
123 *
124 * SUNMatDestroy
125 *   Destroys a matrix created with SUNMatClone.
126 *
127 * SUNMatZero
128 *   Sets all matrix entries to zero
129 *
130 * SUNMatScaleAdd
131 *   Performs the operation A = c*A + B.  Returns an error if A
132 *   and B have different types and/or dimensions.
133 *
134 * SUNMatCopy
135 *   Performs the operation B = A.  Should return an error if A and
136 *   B have different types and/or dimensions.
137 *
138 * SUNMatScaleAddI
139 *   Performs the operation A = c*A + I.  Returns an error if A is
140 *   not a square matrix.
141 *
142 * SUNMatMatvec
143 *   Performs the matrix-vector product y = A*x.  Returns an error if
144 *   A, x and/or y have incompatible types and/or dimensions, or if
145 *   x and y are the same vector.
146 *
147 * SUNMatSpace
148 *   Returns the real and integer workspace requirement for the
149 *   SUNMatrix object.
150 *
151 * -----------------------------------------------------------------
152 *
153 * The following table lists the matrix functions used by
154 * different modules in SUNDIALS. The symbols in the table
155 * have the following meaning:
156 *   D  -  called by dense linear solver modules
157 *   B  -  called by band linear solver modules
158 *   I  -  called by iterative linear solver modules
159 *   S  -  called by sparse linear solver modules
160 *   BP -  called by band preconditioner module
161 *   DP -  called by band-block diagonal preconditioner module
162 *
163 *                                MODULES                 
164 * MATRIX        -----------------------------------------------
165 * FUNCTIONS     CVODE(S)      ARKode      IDA(S)       KINSOL   
166 * ----------------------------------------------------------------
167 *  GetID        D B S BP DP  D B S BP DP  D B S BP DP  D B S BP DP
168 *  Clone        D B S BP DP  D B S BP DP  BP DP
169 *  Destroy      D B S BP DP  D B S BP DP  BP DP
170 *  Zero         D B S BP DP  D B S BP DP  D B S BP DP  D B BP DP
171 *  Copy         D B S BP DP  D B S BP DP
172 *  ScaleAddI    D B S BP DP  D B S BP DP
173 *  ScaleAdd                  D B S BP DP
174 *  Matvec*                   D B S
175 *  Space        D B S BP DP  D B S BP DP  D B S BP DP  D B S BP DP
176 * -----------------------------------------------------------------
177 *  Note: MatrixMatvec is only called by ARKode when solving
178 *        problems having non-identity mass matrix
179 * -----------------------------------------------------------------
180 */
181 
182SUNDIALS_EXPORT SUNMatrix_ID SUNMatGetID(SUNMatrix A);
183SUNDIALS_EXPORT SUNMatrix SUNMatClone(SUNMatrix A);
184SUNDIALS_EXPORT void SUNMatDestroy(SUNMatrix A);
185SUNDIALS_EXPORT int SUNMatZero(SUNMatrix A);
186SUNDIALS_EXPORT int SUNMatCopy(SUNMatrix A, SUNMatrix B);
187SUNDIALS_EXPORT int SUNMatScaleAdd(realtype c, SUNMatrix A, SUNMatrix B);
188SUNDIALS_EXPORT int SUNMatScaleAddI(realtype c, SUNMatrix A);
189SUNDIALS_EXPORT int SUNMatMatvec(SUNMatrix A, N_Vector x, N_Vector y);
190SUNDIALS_EXPORT int SUNMatSpace(SUNMatrix A, long int *lenrw,
191                                long int *leniw);
192 
193#ifdef __cplusplus
194}
195#endif
196#endif
Note: See TracBrowser for help on using the repository browser.