/[ascend]/branches/georgy/disused/solver/linsol.h
ViewVC logotype

Contents of /branches/georgy/disused/solver/linsol.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3105 - (show annotations) (download) (as text)
Tue May 24 01:31:12 2016 UTC (8 years, 1 month ago) by jpye
File MIME type: text/x-chdr
File size: 11249 byte(s)
Creating new branch for [[User:Georgy]] for [[GSOC2016]], from trunk r3104.

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

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