source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/sunmatrix/sunmatrix_band.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: 12.1 KB
Line 
1/*
2 * -----------------------------------------------------------------
3 * Programmer(s): Daniel Reynolds @ SMU
4 *                David Gardner @ LLNL
5 * Based on code sundials_direct.h by: Radu Serban @ LLNL
6 * -----------------------------------------------------------------
7 * LLNS/SMU Copyright Start
8 * Copyright (c) 2017, Southern Methodist University and
9 * Lawrence Livermore National Security
10 *
11 * This work was performed under the auspices of the U.S. Department
12 * of Energy by Southern Methodist University and Lawrence Livermore
13 * National Laboratory under Contract DE-AC52-07NA27344.
14 * Produced at Southern Methodist University and the Lawrence
15 * Livermore National Laboratory.
16 *
17 * All rights reserved.
18 * For details, see the LICENSE file.
19 * LLNS/SMU Copyright End
20 * -----------------------------------------------------------------
21 * This is the header file for the band implementation of the
22 * SUNMATRIX module.
23 *
24 * Part I contains declarations specific to the band implementation
25 * of the supplied SUNMATRIX module.
26 *
27 * Part II defines accessor macros that allow the user to
28 * efficiently use this SUNMatrix type without making explicit
29 * references to the underlying data structure.
30 *
31 * Part III contains the prototype for the constructor
32 * SUNBandMatrix as well as implementation-specific prototypes
33 * for various useful matrix operations.
34 *
35 * Notes:
36 *
37 *   - The definition of the generic SUNMatrix structure can be found
38 *     in the header file sundials_matrix.h.
39 *
40 *   - The definition of the type 'realtype' can be found in the
41 *     header file sundials_types.h, and it may be changed (at the
42 *     configuration stage) according to the user's needs.
43 *     The sundials_types.h file also contains the definition
44 *     for the type 'booleantype' and 'indextype'.
45 *
46 * -----------------------------------------------------------------
47 */
48
49#ifndef _SUNMATRIX_BAND_H
50#define _SUNMATRIX_BAND_H
51
52#include <stdio.h>
53#include <sundials/sundials_matrix.h>
54
55#ifdef __cplusplus  /* wrapper to enable C++ usage */
56extern "C" {
57#endif
58
59/*
60 * -----------------------------------------------------------------
61 * PART I: Band implementation of SUNMatrix
62 *
63 * The band implementation of the SUNMatrix 'content' structure
64 * contains:
65 *   M     - number of rows
66 *   N     - number of columns
67 *   mu    - upper bandwidth, 0 <= mu <= min(M,N)
68 *   ml    - lower bandwidth, 0 <= ml <= min(M,N)
69 *   s_mu  - storage upper bandwidth, mu <= s_mu <= N-1.
70 *           The dgbtrf routine writes the LU factors into the storage
71 *           for A. The upper triangular factor U, however, may have
72 *           an upper bandwidth as big as MIN(N-1,mu+ml) because of
73 *           partial pivoting. The s_mu field holds the upper
74 *           bandwidth allocated for A.
75 *   ldim  - leading dimension (ldim >= s_mu)
76 *   data  - pointer to a contiguous block of realtype variables
77 *   ldata - length of the data array = ldim*(s_mu+ml+1)
78 *   cols  - array of pointers. cols[j] points to the first element
79 *           of the j-th column of the matrix in the array data.
80 * The elements of a band matrix are stored columnwise (i.e. columns
81 * are stored one on top of the other in memory); i.e. if A is a
82 * SUNMatrix_Band object, then the (i,j)th element of A (with
83 * 0 <= i < M and 0 <= j < N) is given by ???
84 *
85 * -----------------------------------------------------------------
86 */
87 
88struct _SUNMatrixContent_Band {
89  sunindextype M;
90  sunindextype N;
91  sunindextype ldim;
92  sunindextype mu;
93  sunindextype ml;
94  sunindextype s_mu;
95  realtype *data;
96  sunindextype ldata;
97  realtype **cols;
98};
99
100typedef struct _SUNMatrixContent_Band *SUNMatrixContent_Band;
101
102 
103/*
104 * -----------------------------------------------------------------
105 * PART II: macros SM_CONTENT_B, SM_DATA_B, SM_ROWS_B, SM_COLUMNS_B,
106 *          SM_UBAND_B, SM_LBAND_B, SM_SUBAND_B, SM_LDIM_B, SM_COLS_B,
107 *          SM_COLUMN_B, SM_COLUMN_ELEMENT_B, and SM_ELEMENT_B
108 * -----------------------------------------------------------------
109 * In the descriptions below, the following user declarations
110 * are assumed:
111 *
112 * SUNMatrix A;
113 * SUNMatrixContent_Band A_cont;
114 * realtype *A_col_j, *A_data, **A_cols, A_ij;
115 * sunindextype i, j, A_rows, A_columns, A_ldata, A_ldim;
116 *
117 * (1) SM_CONTENT_B
118 *
119 *     This macro gives access to the contents of the band
120 *     SUNMatrix
121 *
122 *     The assignment A_cont = SM_CONTENT_B(A) sets A_cont to be
123 *     a pointer to the band SUNMatrix content structure.
124 *
125 * (2) SM_DATA_B, SM_ROWS_B, SM_COLUMNS_B, SM_LDATA_B, SM_LDIM_B,
126 *     SM_UBAND_B, SM_LBAND_B and SM_SUBAND_B
127 *
128 *     These macros give access to the individual parts of
129 *     the content structure of a band SUNMatrix.
130 *
131 *     The assignment A_data = SM_DATA_B(A) sets A_data to be
132 *     a pointer to the first component of A.
133 *
134 *     The assignment A_cols = SM_COLS_B(A) sets A_cols to be
135 *     a pointer to the content's 'cols' entry.
136 *
137 *     The assignment A_rows = SM_ROWS_B(A) sets A_rows to be
138 *     the number of rows in A.
139 *
140 *     The assignment A_columns = SM_COLUMNS_B(A) sets A_columns
141 *     to be the number of columns in A.
142 *
143 *     The assignment A_ldata = SM_LDATA_B(A) sets A_ldata to be
144 *     the length of the data array for A.
145 *
146 *     The assignment A_mu = SM_UBAND_B(A) sets A_mu to be
147 *     the upper bandwidth of A.
148 *
149 *     The assignment A_ml = SM_LBAND_B(A) sets A_lu to be
150 *     the lower bandwidth of A.
151 *
152 *     The assignment A_smu = SM_SUBAND_B(A) sets A_smu to be
153 *     the storage upper bandwidth of A.
154 *
155 *     The assignment A_ldim = SM_LDIM_B(A) sets A_ldim to be
156 *     the length of the leading dimension of A.
157 *
158 * (3) SM_COLUMN_B, SM_COLUMN_ELEMENT_B and SM_ELEMENT_B
159 *
160 *     These macros give access to the individual columns and
161 *     elements of a band SUNMatrix, respectively.  In the
162 *     following, the entries of a SUNMatrix are indexed (i,j)
163 *     where i=0,...,M-1 and j=0,...,N-1.
164 *     
165 *     The assignment A_col_j = SM_COLUMN_B(A,j) sets A_col_j to
166 *     be a pointer to the jth column of the M-by-N band
167 *     matrix A, 0 <= j < N.  After the assignment, A_col_j may
168 *     be treated as an array indexed from -mu to ml.
169 *     The (i,j)-th element of A is thus referenced by col_j[i-j].
170 *
171 *     The assignment A_ij = SM_COLUMN_ELEMENT_B(SM_COLUMN_B(A),i,j)
172 *     sets A_ij to the value of the (i,j)th element of the band
173 *     M-by-N matrix A, when used in conjunction with SM_COLUMN_B. 
174 *     The index (i,j) should satisfy j-mu <= i <= j+ml, with
175 *     0 <= i < M and 0 <= j < N.  Similarly, the assignment 
176 *     SM_COLUMN_ELEMENT_B(SM_COLUMN_B(A),i,j) = A_ij sets the value
177 *     of A_ij into the (i,j) location of the matrix A.
178 *
179 *     The assignment A_ij = SM_ELEMENT_B(A,i,j) sets A_ij to
180 *     the value of the (i,j)th element of the band M-by-N matrix
181 *     A.  The location (i,j) should satisfy j-mu <= i <= j+ml,
182 *     with 0 <= i < M ; 0 <= j < N.  Similarly, the assignment
183 *     SM_ELEMENT_B(A,i,j) = A_ij sets the value of A_ij into the
184 *     (i,j) location of the matrix A.
185 *
186 * -----------------------------------------------------------------
187 */
188
189#define SM_CONTENT_B(A)     ( (SUNMatrixContent_Band)(A->content) )
190
191#define SM_ROWS_B(A)        ( SM_CONTENT_B(A)->M )
192
193#define SM_COLUMNS_B(A)     ( SM_CONTENT_B(A)->N )
194
195#define SM_LDATA_B(A)       ( SM_CONTENT_B(A)->ldata )
196
197#define SM_UBAND_B(A)       ( SM_CONTENT_B(A)->mu )
198
199#define SM_LBAND_B(A)       ( SM_CONTENT_B(A)->ml )
200
201#define SM_SUBAND_B(A)      ( SM_CONTENT_B(A)->s_mu )
202
203#define SM_LDIM_B(A)        ( SM_CONTENT_B(A)->ldim )
204
205#define SM_DATA_B(A)        ( SM_CONTENT_B(A)->data )
206
207#define SM_COLS_B(A)        ( SM_CONTENT_B(A)->cols )
208
209#define SM_COLUMN_B(A,j)    ( ((SM_CONTENT_B(A)->cols)[j])+SM_SUBAND_B(A) )
210
211#define SM_COLUMN_ELEMENT_B(col_j,i,j) (col_j[(i)-(j)])
212
213#define SM_ELEMENT_B(A,i,j) ( (SM_CONTENT_B(A)->cols)[j][(i)-(j)+SM_SUBAND_B(A)] )
214
215
216/*
217 * -----------------------------------------------------------------
218 * PART III: functions exported by sunmatrix_band
219 *
220 * CONSTRUCTORS:
221 *    SUNBandMatrix
222 * OTHER:
223 *    SUNBandMatrix_Print
224 *    SUNBandMatrix_Rows
225 *    SUNBandMatrix_Columns
226 *    SUNBandMatrix_LowerBandwidth
227 *    SUNBandMatrix_UpperBandwidth
228 *    SUNBandMatrix_StoredUpperBandwidth
229 *    SUNBandMatrix_LDim
230 *    SUNBandMatrix_Data
231 *    SUNBandMatrix_Cols
232 *    SUNBandMatrix_Column
233 * -----------------------------------------------------------------
234 */
235
236
237/*
238 * -----------------------------------------------------------------
239 * Function: SUNBandMatrix
240 * -----------------------------------------------------------------
241 * SUNBandMatrix creates and allocates memory for an M-by-N
242 * band matrix with upper bandwidth mu, lower bandwidth ml, and
243 * storage upper bandwidth smu. Pass smu as follows depending on
244 * whether A will be LU factored:
245 *
246 * (1) Pass smu = mu if A will not be factored.
247 *
248 * (2) Pass smu = MIN(N-1,mu+ml) if A will be factored.
249 * -----------------------------------------------------------------
250 */
251
252SUNDIALS_EXPORT SUNMatrix SUNBandMatrix(sunindextype N, sunindextype mu,
253                                        sunindextype ml, sunindextype smu);
254
255/*
256 * -----------------------------------------------------------------
257 * Functions: SUNBandMatrix_Print
258 * -----------------------------------------------------------------
259 * This function prints the content of a M-by-N band matrix A to
260 * a file pointer as it would normally appear on paper.
261 * It is intended as debugging tools with small values of M and N.
262 * The elements are printed using the %g/%lg/%Lg option.
263 * A blank line is printed before and after the matrix.
264 * -----------------------------------------------------------------
265 */
266
267SUNDIALS_EXPORT void SUNBandMatrix_Print(SUNMatrix A, FILE* outfile);
268
269
270/*
271 * -----------------------------------------------------------------
272 * Accessor Functions:
273 *
274 * SUNBandMatrix_Rows
275 *    Returns the number of rows in the banded matrix
276 *
277 * SUNBandMatrix_Columns
278 *    Returns the number of columns in the banded matrix
279 *
280 * SUNBandMatrix_LowerBandwidth
281 *    Returns the number of lower bands in the banded matrix
282 *
283 * SUNBandMatrix_UpperBandwidth
284 *    Returns the number of upper bands in the banded matrix
285 *
286 * SUNBandMatrix_StoredUpperBandwidth
287 *    Returns the number of stored upper bands in the banded matrix
288 *
289 * SUNBandMatrix_LDim
290 *    Returns the length of the leading dimension of A.
291 *
292 * SUNBandMatrix_Data
293 *    Returns a pointer to the data array for the banded matrix
294 *
295 * SUNBandMatrix_Cols
296 *    Returns a pointer to the cols array for the banded matrix
297 *
298 * SUNBandMatrix_Column
299 *    Returns a pointer to the diagonal entry of jth column of the
300 *    banded matrix.  The resulting pointer should be indexed over
301 *    the range -mu to ml.
302 * -----------------------------------------------------------------
303 */
304
305SUNDIALS_EXPORT sunindextype SUNBandMatrix_Rows(SUNMatrix A);
306SUNDIALS_EXPORT sunindextype SUNBandMatrix_Columns(SUNMatrix A);
307SUNDIALS_EXPORT sunindextype SUNBandMatrix_LowerBandwidth(SUNMatrix A);
308SUNDIALS_EXPORT sunindextype SUNBandMatrix_UpperBandwidth(SUNMatrix A);
309SUNDIALS_EXPORT sunindextype SUNBandMatrix_StoredUpperBandwidth(SUNMatrix A);
310SUNDIALS_EXPORT sunindextype SUNBandMatrix_LDim(SUNMatrix A);
311SUNDIALS_EXPORT realtype* SUNBandMatrix_Data(SUNMatrix A);
312SUNDIALS_EXPORT realtype** SUNBandMatrix_Cols(SUNMatrix A);
313SUNDIALS_EXPORT realtype* SUNBandMatrix_Column(SUNMatrix A, sunindextype j);
314
315/*
316 * -----------------------------------------------------------------
317 * band implementations of various useful matrix operations
318 * -----------------------------------------------------------------
319 */
320
321SUNDIALS_EXPORT SUNMatrix_ID SUNMatGetID_Band(SUNMatrix A);
322SUNDIALS_EXPORT SUNMatrix SUNMatClone_Band(SUNMatrix A);
323SUNDIALS_EXPORT void SUNMatDestroy_Band(SUNMatrix A);
324SUNDIALS_EXPORT int SUNMatZero_Band(SUNMatrix A);
325SUNDIALS_EXPORT int SUNMatCopy_Band(SUNMatrix A, SUNMatrix B);
326SUNDIALS_EXPORT int SUNMatScaleAdd_Band(realtype c, SUNMatrix A, SUNMatrix B);
327SUNDIALS_EXPORT int SUNMatScaleAddI_Band(realtype c, SUNMatrix A);
328SUNDIALS_EXPORT int SUNMatMatvec_Band(SUNMatrix A, N_Vector x, N_Vector y);
329SUNDIALS_EXPORT int SUNMatSpace_Band(SUNMatrix A, long int *lenrw, long int *leniw);
330 
331#ifdef __cplusplus
332}
333#endif
334
335#endif
Note: See TracBrowser for help on using the repository browser.