/[ascend]/trunk/ascend4/solver/linsol.h
ViewVC logotype

Contents of /trunk/ascend4/solver/linsol.h

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

Name Value
svn:executable *

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