/[ascend]/trunk/base/generic/solver/linsol.h
ViewVC logotype

Contents of /trunk/base/generic/solver/linsol.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1013 - (show annotations) (download) (as text)
Wed Jan 3 03:41:35 2007 UTC (13 years, 6 months ago) by johnpye
File MIME type: text/x-chdr
File size: 11345 byte(s)
Added doxygen comments for linear routines in base/generic/solver.
Fixed up missing (still unimplemented) idalinear jacobian sjex.
1 /* ASCEND modelling environment
2 Copyright (C) 1990 Karl Michael Westerberg
3 Copyright (C) 1993 Joseph Zaher
4 Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan
5 Copyright (C) 2006 Carnegie Mellon University
6
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2, or (at your option)
10 any later version.
11
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16
17 You should have received a copy of the GNU General Public License
18 along with this program; if not, write to the Free Software
19 Foundation, Inc., 59 Temple Place - Suite 330,
20 Boston, MA 02111-1307, USA.
21 *//** @file
22 ASCEND linear solver
23
24 A linear system consists of a coefficient matrix (A)
25 and possibly several right-hand-sides (rhs). The
26 solution vector x sought can be that of either
27 <pre>
28 T
29 A x = rhs or A x = rhs </pre>
30
31 depending on a specification inherent with rhs which
32 dictates whether or not A should be transposed. If a
33 rhs specifies transpose, then the vector itself is
34 expected to be indexed by the original column numbers
35 of the coefficient matrix and the solution vector shall
36 be indexed by original row numbers. Otherwise, rhs
37 is expected to be indexed by original row numbers while
38 the solution can be referenced using original column
39 numbers. The coefficient matrix and each rhs will be
40 preserved throughout solving, except that the
41 coefficient matrix may be permuted during reordering.
42
43 Requires:
44 #include "utilities/ascConfig.h"
45 #include "mtx.h"
46 *//*
47 by Karl Michael Westerberg, created 2/6/90
48 Last in CVS: $Revision: 1.6 $ $Date: 1997/07/18 12:14:20 $ $Author: mthomas $
49 Authors: Karl Westerberg
50 Joseph Zaher
51 Dates:
52 06/90 - original version
53 04/91 - removed output assignment and partitioning
54 (belong in structural analysis)
55 08/92 - added transpose ability
56 01/94 - broke out linsol_invert() and linsol_solve()
57 */
58
59 #ifndef ASC_LINSOL_H
60 #define ASC_LINSOL_H
61
62 /** @addtogroup linear @{ */
63
64 typedef struct linsol_header *linsol_system_t;
65 /**< linsol_system_t is the linear system handle. */
66
67 extern linsol_system_t linsol_create(void);
68 /**<
69 * Creates a linear system and returns a pointer to it. Initially the
70 * system has no coefficient matrix and no rhs.
71 */
72
73 extern void linsol_destroy(linsol_system_t sys);
74 /**<
75 * Destroys the linear system. The coefficient matrix and each rhs are
76 * not destroyed by this call.
77 */
78
79 extern void linsol_set_matrix(linsol_system_t sys, mtx_matrix_t mtx);
80 /**<
81 * Sets the coefficient matrix to mtx.
82 */
83
84 ASC_DLLSPEC(mtx_matrix_t ) linsol_get_matrix(linsol_system_t sys);
85 /**<
86 * Returns the coefficient matrix.
87 */
88
89 ASC_DLLSPEC(mtx_matrix_t ) linsol_get_inverse(linsol_system_t sys);
90 /**<
91 * Returns the inverse matrix. May be NULL.
92 */
93
94 extern void linsol_add_rhs(linsol_system_t sys,
95 real64 *rhs,
96 boolean transpose);
97 /**<
98 * Adds the given rhs to the collection of rhs's already part of the
99 * system. rhs should point to an array of numbers indexed by original
100 * column number if the linear system is to be solved using the transpose
101 * of the matrix or by original row number if the matrix is not to be
102 * transposed. This is determined using the boolean transpose. The
103 * rhs should be refered to in the future by its pointer.
104 */
105
106 extern void linsol_remove_rhs(linsol_system_t sys, real64 *rhs);
107 /**<
108 * Removes the given rhs from the system. The rhs is not destroyed, just
109 * removed from the system.
110 */
111
112 extern int linsol_number_of_rhs(linsol_system_t sys);
113 /**<
114 * Returns the number of rhs's currently part of the system.
115 */
116
117 ASC_DLLSPEC(real64 *) linsol_get_rhs(linsol_system_t sys, int n);
118 /**<
119 * Returns the n-th rhs, where rhs's are indexed in the order they were
120 * added using linsol_add_rhs() from 0 to (# rhs's)-1. NULL is returned
121 * if the index is out of range.
122 */
123
124 ASC_DLLSPEC(void ) linsol_matrix_was_changed(linsol_system_t sys);
125 /**<
126 * Informs the solver that a numerical value of a non-zero was changed.
127 * This must be called whenever any numerical changes to the matrix are
128 * made.
129 */
130
131 ASC_DLLSPEC(void ) linsol_rhs_was_changed(linsol_system_t sys, real64 *rhs);
132 /**<
133 * Informs the solver that the given rhs has been modified. This must be
134 * called whenever the rhs is modified.
135 */
136
137 extern void linsol_set_pivot_zero(linsol_system_t sys, real64 pivot_zero);
138 /**<
139 * Sets the pivot zero for the system. Pivots less than or equal to
140 * this value are regarded as zero. linsol_set_pivot_zero() will
141 * automatically call linsol_matrix_was_changed().
142 */
143 extern real64 linsol_pivot_zero(linsol_system_t sys);
144 /**<
145 Gets the pivot zero for the system. Pivots less than or equal to
146 this value are regarded as zero.
147
148 Calls linsol_matrix_was_changed().
149 */
150
151 extern void linsol_set_pivot_tolerance(linsol_system_t sys, real64 ptol);
152 /**<
153 * Sets the pivot tolerance for the system. Pivots less than this
154 * fraction of the maximum pivot value in the same row are disregarded.
155 * linsol_set_pivot_tolerance() will automatically call
156 * linsol_matrix_was_changed().
157 */
158 extern real64 linsol_pivot_tolerance(linsol_system_t sys);
159 /**<
160 Gets the pivot tolerance for the system. Pivots less than this
161 fraction of the maximum pivot value in the same row are disregarded.
162
163 Calls linsol_matrix_was_changed().
164 */
165
166 ASC_DLLSPEC(void ) linsol_reorder(linsol_system_t sys, mtx_region_t *region);
167 /**<
168 * The specified region of the coefficient matrix is reordered. This
169 * should be called before inverting the matrix. The specified region
170 * is assumed to contain only nonempty rows and columns.
171 */
172
173 ASC_DLLSPEC(void ) linsol_invert(linsol_system_t sys, mtx_region_t *region);
174 /**<
175 * Decompose the specified region of a copy of the coefficient matrix
176 * into upper and lower triangular factors (if necessary) which can be
177 * inverted easily when applied to any rhs. Matrix must be inverted in
178 * order to perform any of the operations below. The numerical rank and
179 * the smallest pivot encountered during pivoting are computed in the
180 * process.
181 */
182
183 extern int32 linsol_rank(linsol_system_t sys);
184 /**<
185 * Returns the rank of the system. The system must be previously
186 * inverted.
187 */
188
189 extern real64 linsol_smallest_pivot(linsol_system_t sys);
190 /**<
191 * Returns the smallest pivot accepted in solving the system. The
192 * system must be previously inverted. If no pivoting was performed,
193 * MAXDOUBLE is returned.
194 */
195
196 extern int linsol_get_pivot_sets(linsol_system_t sys,
197 unsigned *org_rowpivots,
198 unsigned *org_colpivots);
199 /**<
200 * Returns the set of original row numbers / original column numbers which
201 * have been pivoted. org_rowpivots and org_colpivots are assumed to be
202 * sets created by (or at least for) the set module with sufficient size
203 * before calling this function. They must also be previously NULLed.
204 * The system must be previously inverted.
205 * The sets input should be the result of set_create(neqn),set_create(nvar).
206 * There is no association of rows with columns here.<br><br>
207 *
208 * Status is 0 if not inverted, 1 if inverted. if 0, sets will not be
209 * changed.
210 */
211
212 extern int32 linsol_org_row_to_org_col(linsol_system_t sys,
213 int32 org_row);
214 /**<
215 * Returns the org_col associated with the given org_row/org_col.
216 * Pivoted original columns and pivoted original rows can be associated
217 * with one another via the pivot sequence. If the given
218 * org_row is not pivoted, a meaningless value is returned. The
219 * system must be previously inverted. If not inverted, a value will be
220 * returned, but linsol may reorder making the value wrong.
221 */
222 extern int32 linsol_org_col_to_org_row(linsol_system_t sys,
223 int32 org_col);
224 /**<
225 * Returns the org_row associated with the given org_col.
226 * Pivoted original columns and pivoted original rows can be associated
227 * with one another via the pivot sequence. If the given
228 * org_col is not pivoted, a meaningless value is returned. The
229 * system must be previously inverted. If not inverted, a value is returned,these functions
230 * but linsol may reorder making the value wrong.
231 */
232
233 extern real64 linsol_org_row_dependency(linsol_system_t sys,
234 int32 dep, int32 ind);
235 /**< See linsol_org_col_dependency(). */
236 extern real64 linsol_org_col_dependency(linsol_system_t sys,
237 int32 dep, int32 ind);
238 /**<
239 * Any original row / column of the coefficient matrix which when submitted
240 * to the linear solver is not pivoted, is called dependent and can be
241 * written as a linear combination of the independent (pivoted) original
242 * rows / columns. These functions return the previously computed
243 * coefficients of the linear combination. The system must be previously
244 * inverted and the independent row / column must be a member of the
245 * set of row / column pivots obtained by linsol_get_pivot_sets.
246 */
247
248 ASC_DLLSPEC(void ) linsol_solve(linsol_system_t sys, real64 *rhs);
249 /**<
250 * Solves the system of linear equations (if necessary) utilizing the
251 * specified rhs along with the previously inverted matrix. The rhs
252 * is automatically checked if the matrix factors need to be transposed
253 * or not.
254 */
255
256 extern real64 linsol_var_value(linsol_system_t sys,
257 real64 *rhs, int32 var);
258 /**<
259 * Returns the value of the variable in the solution vector associated
260 * with the given rhs and either the matrix or its transpose. The rhs
261 * must be solved for first. If rhs specifies transpose, then var is
262 * expected to be an original row number, otherwise it should be an
263 * original column number.
264 */
265
266 ASC_DLLSPEC(boolean ) linsol_copy_solution(linsol_system_t sys,
267 real64 *rhs, real64 *vector);
268 /**<
269 * Will copy the solution vector into the vector provided.
270 * The user is responsible for allocating and deallocating said
271 * vector. The provided vector should be at least
272 * mtx_cacpacity(mtx), where mtx is the matrix that linsol_set_matrix,
273 * was called with. The returned vector will be indexed in the same
274 * way that the rhs is indexed.<br><br>
275 *
276 * Returns TRUE in the event of any of any errors, FALSE otherwise.
277 */
278
279 extern real64 linsol_eqn_residual(linsol_system_t sys,
280 real64 *rhs, int32 eqn);
281 /**<
282 * Returns the equation residual using the solution vector associated
283 * with the given rhs and either the matrix or its transpose.
284 * <pre>
285 * T
286 * residual = A x - b or residual = A x - b
287 * </pre>
288 * The rhs must be solved for first. If rhs specifies transpose, then
289 * eqn is expected to be an original column number, otherwise it should
290 * be an original row number.
291 */
292
293 /** @} */
294
295 #endif /* ASC_LINSOL_H */
296

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22