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 */ |
---|
35 | extern "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 | |
---|
84 | SUNDIALS_EXPORT sunindextype BandGBTRF(DlsMat A, sunindextype *p); |
---|
85 | SUNDIALS_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 | |
---|
105 | SUNDIALS_EXPORT void BandGBTRS(DlsMat A, sunindextype *p, realtype *b); |
---|
106 | SUNDIALS_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 | |
---|
124 | SUNDIALS_EXPORT void BandCopy(DlsMat A, DlsMat B, sunindextype copymu, sunindextype copyml); |
---|
125 | SUNDIALS_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 | |
---|
143 | SUNDIALS_EXPORT void BandScale(realtype c, DlsMat A); |
---|
144 | SUNDIALS_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 | |
---|
155 | SUNDIALS_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 | |
---|
172 | SUNDIALS_EXPORT void BandMatvec(DlsMat A, realtype *x, realtype *y); |
---|
173 | SUNDIALS_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 |
---|