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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1 - (hide annotations) (download) (as text)
Fri Oct 29 20:54:12 2004 UTC (17 years, 8 months ago) by aw0a
File MIME type: text/x-chdr
File size: 12678 byte(s)
Setting up web subdirectory in repository
1 aw0a 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