source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/sunmatrix/sunmatrix_sparse.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: 13.5 KB
Line 
1/*
2 * -----------------------------------------------------------------
3 * Programmer(s): Daniel Reynolds @ SMU
4 *                David Gardner @ LLNL
5 * Based on code sundials_sparse.h by: Carol Woodward and
6 *     Slaven Peles @ LLNL, and Daniel R. Reynolds @ SMU
7 * -----------------------------------------------------------------
8 * LLNS/SMU Copyright Start
9 * Copyright (c) 2017, Southern Methodist University and
10 * Lawrence Livermore National Security
11 *
12 * This work was performed under the auspices of the U.S. Department
13 * of Energy by Southern Methodist University and Lawrence Livermore
14 * National Laboratory under Contract DE-AC52-07NA27344.
15 * Produced at Southern Methodist University and the Lawrence
16 * Livermore National Laboratory.
17 *
18 * All rights reserved.
19 * For details, see the LICENSE file.
20 * LLNS/SMU Copyright End
21 * -----------------------------------------------------------------
22 * This is the header file for the sparse implementation of the
23 * SUNMATRIX module.
24 *
25 * Part I contains declarations specific to the sparse implementation
26 * of the supplied SUNMATRIX module.
27 *
28 * Part II defines accessor macros that allow the user to
29 * efficiently use this SUNMatrix type without making explicit
30 * references to the underlying data structure.
31 *
32 * Part III contains the prototype for the constructor
33 * SUNMatrixNew_Sparse as well as implementation-specific prototypes
34 * for various useful matrix operations.
35 *
36 * Notes:
37 *
38 *   - The definition of the generic SUNMatrix structure can be found
39 *     in the header file sundials_matrix.h.
40 *
41 *   - The definition of the type 'realtype' can be found in the
42 *     header file sundials_types.h, and it may be changed (at the
43 *     configuration stage) according to the user's needs.
44 *     The sundials_types.h file also contains the definition
45 *     for the type 'booleantype' and 'indextype'.
46 *
47 * -----------------------------------------------------------------
48 */
49
50#ifndef _SUNMATRIX_SPARSE_H
51#define _SUNMATRIX_SPARSE_H
52
53#include <stdio.h>
54#include <sundials/sundials_matrix.h>
55#include <sunmatrix/sunmatrix_dense.h>
56#include <sunmatrix/sunmatrix_band.h>
57
58#ifdef __cplusplus  /* wrapper to enable C++ usage */
59extern "C" {
60#endif
61
62/*
63 * ==================================================================
64 * Type definitions
65 * ==================================================================
66 */
67
68#define CSC_MAT 0
69#define CSR_MAT 1
70
71 
72/*
73 * -----------------------------------------------------------------
74 * PART I: Sparse implementation of SUNMatrix
75 *
76 * The sparse implementation of the SUNMatrix 'content' structure
77 * contains:
78 *   M     - number of rows
79 *   N     - number of columns
80 *   NNZ   - the number of nonzero entries in the matrix
81 *   NP    - number of index pointers
82 *   data  - pointer to a contiguous block of realtype variables
83 *   sparsetype - type of sparse matrix: compressed sparse column or row
84 *   indexvals  - indices of each nonzero entry (columns or rows)
85 *   indexptrs  - starting index of the first entry in data for each slice
86 *   rowvals - pointer to row indices of each nonzero entry
87 *   colptrs - pointer to starting indices in data array for each column
88 *   colvals - pointer to column indices of each nonzero entry
89 *   rowptrs - pointer to starting indices in data array for each row
90 * -----------------------------------------------------------------
91 */
92 
93struct _SUNMatrixContent_Sparse {
94  sunindextype M;
95  sunindextype N;
96  sunindextype NNZ;
97  sunindextype NP;
98  realtype *data;
99  int sparsetype;
100  sunindextype *indexvals;
101  sunindextype *indexptrs;
102  /* CSC indices */
103  sunindextype **rowvals;
104  sunindextype **colptrs;
105  /* CSR indices */
106  sunindextype **colvals;
107  sunindextype **rowptrs;
108};
109
110typedef struct _SUNMatrixContent_Sparse *SUNMatrixContent_Sparse;
111
112
113/*
114 * -----------------------------------------------------------------
115 * PART II: macros SM_CONTENT_S, SM_ROWS_S, SM_COLUMNS_S, SM_NNZ_S,
116 *          SM_NP_S, SM_SPARSETYPE_S, SM_DATA_S, SM_INDEXVALS_S, and
117 *          SM_INDEXPTRS_S
118 * -----------------------------------------------------------------
119 * In the descriptions below, the following user declarations
120 * are assumed:
121 *
122 * SUNMatrix A;
123 * SUNMatrixContent_Sparse A_cont;
124 * realtype *A_data;
125 * int A_type;
126 * sunindextype A_nnz, A_np, *A_ivals, *A_iptrs;
127 *
128 * (1) SM_CONTENT_S
129 *
130 *     This macro gives access to the contents of the sparse
131 *     SUNMatrix
132 *
133 *     The assignment A_cont = SM_CONTENT_S(A) sets A_cont to be
134 *     a pointer to the sparse SUNMatrix content structure.
135 *
136 * (2) SM_ROWS_D, SM_COLUMNS_D, SM_NNZ_S, SM_NP_S, SM_SPARSETYPE_S,
137 *     SM_DATA_S, SM_INDEXVALS_S and SM_INDEXPTRS_S
138 *
139 *     These macros give access to the individual parts of
140 *     the content structure of a sparse SUNMatrix.
141 *
142 *     The assignment A_rows = SM_ROWS_S(A) sets A_rows to be
143 *     the number of rows in A.
144 *
145 *     The assignment A_cols = SM_COLUMNS_S(A) sets A_cols to be
146 *     the number of columns in A.
147 *
148 *     The assignment A_nnz = SM_NNZ_S(A) sets A_nnz to be
149 *     the number of nonzero entries in A.
150 *
151 *     The assignment A_np = SM_NP_S(A) sets A_np to be
152 *     the number of index pointers in A.
153 *
154 *     The assignment A_type = SM_SPARSETYPE_S(A) sets A_type to be
155 *     the type of sparse matrix that A is (CSC_MAT or CSR_MAT).
156 *
157 *     The assignment A_data = SM_DATA_S(A) sets A_data to be
158 *     a pointer to the first component of the data array for A.
159 *
160 *     The assignment A_ivals = SM_INDEXVALS_S(A) sets A_ivals to be
161 *     a pointer to the array of index values of each nonzero entry in A.
162 *
163 *     The assignment A_iptrs = SM_INDEXPTRS_S(A) sets A_iptrs to be
164 *     a pointer to the array of starting indices for the first entry
165 *     of each row/column in the data/indexvals arrays.
166 *
167 * -----------------------------------------------------------------
168 */
169
170#define SM_CONTENT_S(A)     ( (SUNMatrixContent_Sparse)(A->content) )
171
172#define SM_ROWS_S(A)        ( SM_CONTENT_S(A)->M )
173
174#define SM_COLUMNS_S(A)     ( SM_CONTENT_S(A)->N )
175
176#define SM_NNZ_S(A)         ( SM_CONTENT_S(A)->NNZ )
177
178#define SM_NP_S(A)          ( SM_CONTENT_S(A)->NP )
179
180#define SM_SPARSETYPE_S(A)  ( SM_CONTENT_S(A)->sparsetype )
181
182#define SM_DATA_S(A)        ( SM_CONTENT_S(A)->data )
183
184#define SM_INDEXVALS_S(A)   ( SM_CONTENT_S(A)->indexvals )
185
186#define SM_INDEXPTRS_S(A)   ( SM_CONTENT_S(A)->indexptrs )
187
188/*
189 * -----------------------------------------------------------------
190 * PART III: functions exported by sunmatrix_sparse
191 *
192 * CONSTRUCTORS:
193 *    SUNSparseMatrix
194 *    SUNSparseFromDenseMatrix
195 *    SUNSparseFromBandMatrix
196 * OTHER:
197 *    SUNSparseMatrix_Print
198 *    SUNSparseMatrix_Realloc
199 *    SUNSparseMatrix_Reallocate
200 *    SUNSparseMatrix_Rows
201 *    SUNSparseMatrix_Columns
202 *    SUNSparseMatrix_NNZ
203 *    SUNSparseMatrix_NP
204 *    SUNSparseMatrix_SparseType
205 *    SUNSparseMatrix_Data
206 *    SUNSparseMatrix_IndexValues
207 *    SUNSparseMatrix_IndexPointers
208 * -----------------------------------------------------------------
209 */
210
211/*
212 * -----------------------------------------------------------------
213 * Function: SUNSparseMatrix
214 * -----------------------------------------------------------------
215 * Creates and allocates memory for an M-by-N sparse SUNMatrix of
216 * type sparsetype.
217 * Requirements: M and N must be strictly positive; NNZ must be
218 * non-negative; sparsetype must be either CSC_MAT or CSR_MAT;
219 * Returns NULL if any requirements are violated, or if the matrix
220 * storage request cannot be satisfied.
221 * -----------------------------------------------------------------
222 */
223
224SUNDIALS_EXPORT SUNMatrix SUNSparseMatrix(sunindextype M, sunindextype N,
225                                          sunindextype NNZ, int sparsetype);
226
227/*
228 * -----------------------------------------------------------------
229 * Function: SUNSparseFromDenseMatrix
230 * -----------------------------------------------------------------
231 * Creates a new sparse matrix from an existing dense matrix
232 * by copying all values with magnitude larger than droptol into
233 * the sparse matrix structure. 
234 * Requirements: A must have type SUNMATRIX_DENSE;
235 * droptol must be non-negative; sparsetype must be either
236 * CSC_MAT or CSR_MAT.
237 * Returns NULL if any requirements are violated, or if the matrix
238 * storage request cannot be satisfied.
239 * -----------------------------------------------------------------
240 */
241
242SUNDIALS_EXPORT SUNMatrix SUNSparseFromDenseMatrix(SUNMatrix A,
243                                                   realtype droptol,
244                                                   int sparsetype);
245
246/*
247 * -----------------------------------------------------------------
248 * Function: SUNSparseFromBandMatrix
249 * -----------------------------------------------------------------
250 * Creates a new sparse matrix from an existing band matrix
251 * by copying all values with magnitude larger than or equal to
252 * droptol into the sparse matrix structure. 
253 * Requirements: A must have type SUNMATRIX_BAND;
254 * droptol must be non-negative; sparsetype must be either
255 * CSC_MAT or CSR_MAT.
256 * Returns NULL if any requirements are violated, or if the matrix
257 * storage request cannot be satisfied.
258 * -----------------------------------------------------------------
259 */
260
261SUNDIALS_EXPORT SUNMatrix SUNSparseFromBandMatrix(SUNMatrix A,
262                                                  realtype droptol,
263                                                  int sparsetype);
264
265/*
266 * -----------------------------------------------------------------
267 * Functions: SUNSparseMatrix_Realloc
268 * -----------------------------------------------------------------
269 * This function reallocates internal arrays so that the resulting
270 * sparse matrix holds colptrs[N] nonzeros.  Returns 0 on success and
271 * 1 on failure (e.g. if A does not have sparse type)
272 * -----------------------------------------------------------------
273 */
274
275SUNDIALS_EXPORT int SUNSparseMatrix_Realloc(SUNMatrix A);
276
277/*
278 * -----------------------------------------------------------------
279 * Functions: SUNSparseMatrix_Reallocate
280 * -----------------------------------------------------------------
281 * This function reallocates internal arrays so that the resulting
282 * sparse matrix has storage for a specified number of nonzeros. 
283 * Returns 0 on success and 1 on failure (e.g. if A does not have
284 * sparse type, or if nnz is negative)
285 * -----------------------------------------------------------------
286 */
287
288SUNDIALS_EXPORT int SUNSparseMatrix_Reallocate(SUNMatrix A, sunindextype NNZ);
289
290/*
291 * -----------------------------------------------------------------
292 * Functions: SUNSparseMatrix_Print
293 * -----------------------------------------------------------------
294 * This function prints the sparse matrix information to a file
295 * pointer.  It is intended as a debugging tool with small values
296 * of NNZ.  The elements are printed using the %g/%lg/%Lg option.
297 * A blank line is printed before and after the matrix.
298 * -----------------------------------------------------------------
299 */
300
301SUNDIALS_EXPORT void SUNSparseMatrix_Print(SUNMatrix A, FILE* outfile);
302
303
304/*
305 * -----------------------------------------------------------------
306 * Accessor Functions:
307 *
308 * SUNSparseMatrix_Rows
309 *    Returns the number of rows in the sparse matrix
310 *
311 * SUNSparseMatrix_Columns
312 *    Returns the number of columns in the sparse matrix
313 *
314 * SUNSparseMatrix_NNZ
315 *    Returns the allocated number of nonzeros in the sparse matrix
316 *
317 * SUNSparseMatrix_NP
318 *    Returns the number of columns/rows depending on whether the
319 *    matrix uses CSC/CSR format, respectively
320 *
321 * SUNSparseMatrix_SparseType
322 *    Returns the storage type for this matrix (CSR_MAT or CSC_MAT)
323 *
324 * SUNSparseMatrix_Data
325 *    Returns a pointer to the data array for the sparse matrix
326 *
327 * SUNSparseMatrix_IndexValues
328 *    Returns a ptr to the index value array for the sparse matrix:
329 *    for CSR this is the column index for each nonzero,
330 *    for CSC this is the row index for each nonzero.
331 *
332 * SUNSparseMatrix_IndexPointers
333 *    Returns a ptr to the index pointer array for the sparse matrix:
334 *    for CSR this is the location of the first entry of each row,
335 *    for CSC this is the location of the first entry of each column.
336 * -----------------------------------------------------------------
337 */
338
339SUNDIALS_EXPORT sunindextype SUNSparseMatrix_Rows(SUNMatrix A);
340SUNDIALS_EXPORT sunindextype SUNSparseMatrix_Columns(SUNMatrix A);
341SUNDIALS_EXPORT sunindextype SUNSparseMatrix_NNZ(SUNMatrix A);
342SUNDIALS_EXPORT sunindextype SUNSparseMatrix_NP(SUNMatrix A);
343SUNDIALS_EXPORT int SUNSparseMatrix_SparseType(SUNMatrix A);
344SUNDIALS_EXPORT realtype* SUNSparseMatrix_Data(SUNMatrix A);
345SUNDIALS_EXPORT sunindextype* SUNSparseMatrix_IndexValues(SUNMatrix A);
346SUNDIALS_EXPORT sunindextype* SUNSparseMatrix_IndexPointers(SUNMatrix A);
347
348/*
349 * -----------------------------------------------------------------
350 * sparse implementations of various useful matrix operations
351 * -----------------------------------------------------------------
352 */
353
354SUNDIALS_EXPORT SUNMatrix_ID SUNMatGetID_Sparse(SUNMatrix A);
355SUNDIALS_EXPORT SUNMatrix SUNMatClone_Sparse(SUNMatrix A);
356SUNDIALS_EXPORT void SUNMatDestroy_Sparse(SUNMatrix A);
357SUNDIALS_EXPORT int SUNMatZero_Sparse(SUNMatrix A);
358SUNDIALS_EXPORT int SUNMatCopy_Sparse(SUNMatrix A, SUNMatrix B);
359SUNDIALS_EXPORT int SUNMatScaleAdd_Sparse(realtype c, SUNMatrix A, SUNMatrix B);
360SUNDIALS_EXPORT int SUNMatScaleAddI_Sparse(realtype c, SUNMatrix A);
361SUNDIALS_EXPORT int SUNMatMatvec_Sparse(SUNMatrix A, N_Vector x, N_Vector y);
362SUNDIALS_EXPORT int SUNMatSpace_Sparse(SUNMatrix A, long int *lenrw,
363                                       long int *leniw);
364
365
366#ifdef __cplusplus
367}
368#endif
369
370#endif
Note: See TracBrowser for help on using the repository browser.