source: branches/2925_AutoDiffForDynamicalModels/HeuristicLab.Problems.DynamicalSystemsModelling/3.3/sundials/include/sundials/sundials_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: 7.6 KB
Line 
1/*
2 * -----------------------------------------------------------------
3 * $Revision$
4 * $Date$
5 * -----------------------------------------------------------------
6 * Programmer(s): Alan C. Hindmarsh and Radu Serban @ LLNL
7 * -----------------------------------------------------------------
8 * LLNS Copyright Start
9 * Copyright (c) 2014, Lawrence Livermore National Security
10 * This work was performed under the auspices of the U.S. Department
11 * of Energy by Lawrence Livermore National Laboratory in part under
12 * Contract W-7405-Eng-48 and in part under Contract DE-AC52-07NA27344.
13 * Produced at the Lawrence Livermore National Laboratory.
14 * All rights reserved.
15 * For details, see the LICENSE file.
16 * LLNS Copyright End
17 * -----------------------------------------------------------------
18 * This is the header file for a generic BAND linear solver
19 * package, based on the DlsMat type defined in sundials_direct.h.
20 *
21 * There are two sets of band solver routines listed in
22 * this file: one set uses type DlsMat defined below and the
23 * other set uses the type realtype ** for band matrix arguments.
24 * Routines that work with the type DlsMat begin with "Band".
25 * Routines that work with realtype ** begin with "band"
26 * -----------------------------------------------------------------
27 */
28
29#ifndef _SUNDIALS_BAND_H
30#define _SUNDIALS_BAND_H
31
32#include <sundials/sundials_direct.h>
33
34#ifdef __cplusplus  /* wrapper to enable C++ usage */
35extern "C" {
36#endif
37
38/*
39 * -----------------------------------------------------------------
40 * Function : BandGBTRF
41 * -----------------------------------------------------------------
42 * Usage : ier = BandGBTRF(A, p);
43 *         if (ier != 0) ... A is singular
44 * -----------------------------------------------------------------
45 * BandGBTRF performs the LU factorization of the N by N band
46 * matrix A. This is done using standard Gaussian elimination
47 * with partial pivoting.
48 *
49 * A successful LU factorization leaves the "matrix" A and the
50 * pivot array p with the following information:
51 *
52 * (1) p[k] contains the row number of the pivot element chosen
53 *     at the beginning of elimination step k, k=0, 1, ..., N-1.
54 *
55 * (2) If the unique LU factorization of A is given by PA = LU,
56 *     where P is a permutation matrix, L is a lower triangular
57 *     matrix with all 1's on the diagonal, and U is an upper
58 *     triangular matrix, then the upper triangular part of A
59 *     (including its diagonal) contains U and the strictly lower
60 *     triangular part of A contains the multipliers, I-L.
61 *
62 * BandGBTRF returns 0 if successful. Otherwise it encountered
63 * a zero diagonal element during the factorization. In this case
64 * it returns the column index (numbered from one) at which
65 * it encountered the zero.
66 *
67 * Important Note: A must be allocated to accommodate the increase
68 * in upper bandwidth that occurs during factorization. If
69 * mathematically, A is a band matrix with upper bandwidth mu and
70 * lower bandwidth ml, then the upper triangular factor U can
71 * have upper bandwidth as big as smu = MIN(n-1,mu+ml). The lower
72 * triangular factor L has lower bandwidth ml. Allocate A with
73 * call A = BandAllocMat(N,mu,ml,smu), where mu, ml, and smu are
74 * as defined above. The user does not have to zero the "extra"
75 * storage allocated for the purpose of factorization. This will
76 * handled by the BandGBTRF routine.
77 *
78 * BandGBTRF is only a wrapper around bandGBTRF. All work is done
79 * in bandGBTRF, which works directly on the data in the DlsMat A
80 * (i.e. in the field A->cols).
81 * -----------------------------------------------------------------
82 */
83
84SUNDIALS_EXPORT sunindextype BandGBTRF(DlsMat A, sunindextype *p);
85SUNDIALS_EXPORT sunindextype bandGBTRF(realtype **a, sunindextype n, sunindextype mu, sunindextype ml,
86                                   sunindextype smu, sunindextype *p);
87
88/*
89 * -----------------------------------------------------------------
90 * Function : BandGBTRS
91 * -----------------------------------------------------------------
92 * Usage : BandGBTRS(A, p, b);
93 * -----------------------------------------------------------------
94 * BandGBTRS solves the N-dimensional system A x = b using
95 * the LU factorization in A and the pivot information in p
96 * computed in BandGBTRF. The solution x is returned in b. This
97 * routine cannot fail if the corresponding call to BandGBTRF
98 * did not fail.
99 *
100 * BandGBTRS is only a wrapper around bandGBTRS which does all the
101 * work directly on the data in the DlsMat A (i.e. in A->cols).
102 * -----------------------------------------------------------------
103 */
104
105SUNDIALS_EXPORT void BandGBTRS(DlsMat A, sunindextype *p, realtype *b);
106SUNDIALS_EXPORT void bandGBTRS(realtype **a, sunindextype n, sunindextype smu,
107                               sunindextype ml, sunindextype *p, realtype *b);
108
109/*
110 * -----------------------------------------------------------------
111 * Function : BandCopy
112 * -----------------------------------------------------------------
113 * Usage : BandCopy(A, B, copymu, copyml);
114 * -----------------------------------------------------------------
115 * BandCopy copies the submatrix with upper and lower bandwidths
116 * copymu, copyml of the N by N band matrix A into the N by N
117 * band matrix B.
118 *
119 * BandCopy is a wrapper around bandCopy which accesses the data
120 * in the DlsMat A and DlsMat B (i.e. the fields cols)
121 * -----------------------------------------------------------------
122 */
123
124SUNDIALS_EXPORT void BandCopy(DlsMat A, DlsMat B, sunindextype copymu, sunindextype copyml);
125SUNDIALS_EXPORT void bandCopy(realtype **a, realtype **b, sunindextype n,
126                              sunindextype a_smu, sunindextype b_smu,
127            sunindextype copymu, sunindextype copyml);
128
129/*
130 * -----------------------------------------------------------------
131 * Function: BandScale
132 * -----------------------------------------------------------------
133 * Usage : BandScale(c, A);
134 * -----------------------------------------------------------------
135 * A(i,j) <- c*A(i,j),   j-(A->mu) <= i <= j+(A->ml).
136 *
137 * BandScale is a wrapper around bandScale which performs the actual
138 * scaling by accessing the data in the DlsMat A (i.e. the field
139 * A->cols).
140 * -----------------------------------------------------------------
141 */
142
143SUNDIALS_EXPORT void BandScale(realtype c, DlsMat A);
144SUNDIALS_EXPORT void bandScale(realtype c, realtype **a, sunindextype n, sunindextype mu, sunindextype ml, sunindextype smu);
145
146/*
147 * -----------------------------------------------------------------
148 * Function: bandAddIdentity
149 * -----------------------------------------------------------------
150 * bandAddIdentity adds the identity matrix to the n-by-n matrix
151 * stored in the realtype** arrays.
152 * -----------------------------------------------------------------
153 */
154
155SUNDIALS_EXPORT void bandAddIdentity(realtype **a, sunindextype n, sunindextype smu);
156
157
158/*
159 * -----------------------------------------------------------------
160 * Function: BandMatvec
161 * -----------------------------------------------------------------
162 * BandMatvec computes the matrix-vector product y = A*x, where A
163 * is an M-by-N band matrix, x is a vector of length N, and y is a
164 * vector of length M.  No error checking is performed on the length
165 * of the arrays x and y.  Only y is modified in this routine.
166 *
167 * BandMatvec is a wrapper around bandMatvec which performs the
168 * actual product by accessing the data in the DlsMat A.
169 * -----------------------------------------------------------------
170 */
171
172SUNDIALS_EXPORT void BandMatvec(DlsMat A, realtype *x, realtype *y);
173SUNDIALS_EXPORT void bandMatvec(realtype **a, realtype *x, realtype *y, sunindextype n,
174    sunindextype mu, sunindextype ml, sunindextype smu);
175
176#ifdef __cplusplus
177}
178#endif
179
180#endif
Note: See TracBrowser for help on using the repository browser.