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

Annotation of /trunk/base/generic/solver/mtx_perms.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 522 - (hide annotations) (download) (as text)
Fri Apr 21 07:22:20 2006 UTC (16 years, 3 months ago) by johnpye
File MIME type: text/x-chdr
File size: 27459 byte(s)
Fixed all the missing symbols so that ASCEND Tcl/Tk interface builds with separate 'ascendtcl.dll'.
Split Driver.c across Driver.c and new main.c, which has no Tcl/Tk references.

1 jds 54 /*
2 aw0a 1 * mtx: Ascend Sparse Matrix Package
3     * by Benjamin Andrew Allan
4     * Derived from mtx by Karl Michael Westerberg
5     * Created: 5/3/90
6     * Version: $Revision: 1.10 $
7     * Version control file: $RCSfile: mtx_perms.h,v $
8     * Date last modified: $Date: 1998/05/06 17:28:54 $
9     * Last modified by: $Author: ballan $
10     *
11     * This file is part of the SLV solver.
12     *
13     * Copyright (C) 1996 Benjamin Andrew Allan
14     *
15     * The SLV solver is free software; you can redistribute
16     * it and/or modify it under the terms of the GNU General Public License as
17     * published by the Free Software Foundation; either version 2 of the
18     * License, or (at your option) any later version.
19     *
20     * The SLV solver is distributed in hope that it will be
21     * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
22     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23     * General Public License for more details.
24     *
25     * You should have received a copy of the GNU General Public License along with
26     * the program; if not, write to the Free Software Foundation, Inc., 675
27     * Mass Ave, Cambridge, MA 02139 USA. Check the file named COPYING.
28     * COPYING is found in ../compiler.
29     */
30 jds 54
31     /** @file
32     * mtx2: Ascend Sparse Matrix Package.
33     * <pre>
34     * requires: #include "utilities/ascConfig.h"
35     * requires: #include "mtx.h"
36     * </pre>
37     */
38    
39 aw0a 1 #ifndef __MTX_PERMS_H_SEEN__
40     #define __MTX_PERMS_H_SEEN__
41    
42 jds 54 /* the following block_perm functions are not yet implemented:
43     * this is the software spec. 5/3/95 baa. */
44 aw0a 1
45 jds 54 extern mtx_block_perm_t mtx_create_block_perm(mtx_matrix_t mtx);
46 ben.allan 33 /**<
47 jds 54 *** <!-- bp = mtx_create_block_perm(mtx); -->
48     *** <!-- mtx_matrix_t mtx; -->
49     *** <!-- mtx_block_perm_t bp; -->
50     ***
51 aw0a 1 *** Returns a token with the permutation/block information of the
52     *** mtx given. The mtx given must be previously output assigned and,
53     *** if it is to be partitioned, should already be partitioned.
54     *** The permutation returned can be used subsequently in various
55     *** ways, but all operations must be on the mtx the data came from.
56     *** If the matrix is reoutput assigned or repartitioned, the data
57     *** in bp becomes (potentially) invalid and should be completely
58     *** updated with mtx_update_block_perm.
59 jds 54 *** Returns NULL if a bad mtx is detected.<br><br>
60 aw0a 1 ***
61 jds 54 *** Passes calls on slave matrices up to the master matrix.<br><br>
62 aw0a 1 ***
63     -$- Checks extra carefully for a bad matrix, and returns NULL if so.
64     **/
65    
66 jds 54 extern int mtx_update_block_perm(mtx_matrix_t mtx,
67     int32 bnum,
68     mtx_block_perm_t bperm);
69     /**<
70     *** <!-- mtx_update_block_perm(mtx,bnum,bperm); -->
71     *** <!-- mtx_matrix_t mtx; -->
72     *** <!-- int32 bnum; -->
73     *** <!-- mtx_block_perm_t bperm; -->
74     ***
75 aw0a 1 *** Given an mtx, a block number, and an existing bperm, this
76     *** routine updates the bperm permutation information about the
77     *** block bnum in the mtx.
78     *** The bperm updated must come from the mtx the bperm was created
79     *** for. The mtx must be output assigned and, if the mtx was
80     *** partitioned, the partition data must be consistent between the
81 jds 54 *** bperm and the mtx. The mtx cannot have been resized.<br><br>
82 aw0a 1 ***
83     *** Exceptions: If bnum is mtx_ALL_BLOCKS, we check only for the
84     *** mtx identity and output assignment. All previous permutation and
85     *** block information is ignored and replace by current info.
86     *** Calling with mtx_ALL_BLOCKS is substantially more expensive
87     *** than calling with a specific block number unless the block is
88 jds 54 *** nearly the size of the problem.<br><br>
89 aw0a 1 ***
90 jds 54 *** Passes calls on slave matrices up to the master matrix.<br><br>
91 aw0a 1 ***
92     *** Returns 1 from a bad matrix, 2 from a bad bperm, 3 from a mismatch.
93 jds 54 *** Returns 0 from a successful call.<br><br>
94 aw0a 1 ***
95     -$- Does excessive result checking, and then returns 3 if the
96     -$- excessive checks fail.
97     **/
98    
99 jds 54 extern int mtx_restore_block_perm(mtx_matrix_t mtx,
100     int32 bnum,
101     mtx_block_perm_t bperm);
102     /**<
103     *** <!-- mtx_restore_block_perm(mtx,bnum,bperm); -->
104     *** <!-- mtx_matrix_t mtx; -->
105     *** <!-- int32 bnum; -->
106     *** <!-- mtx_block_perm_t bperm; -->
107     ***
108 aw0a 1 *** Given an mtx, a block number, and an existing bperm, this
109     *** routine updates the mtx permutation information for the
110     *** block bnum using the bperm.
111     *** The mtx updated must go with the bperm.
112     *** The mtx must be output assigned and, if the mtx was
113     *** partitioned, the partition data must be consistent between the
114     *** bperm and the mtx. The mtx cannot have been resized.
115     *** The parity of the mtx will be set to that stored with the bperm;
116 jds 54 *** if you try to do sneaky things, parity may get out of whack.<br><br>
117 aw0a 1 ***
118     *** Exceptions: If bnum is mtx_ALL_BLOCKS, we check only for the
119     *** mtx identity and order. All previous permutation and
120     *** block information is ignored and replaced by bperm info.
121     *** The mtx's output_assigned and partition characteristics will
122     *** be restored to their values at the time the bperm was last
123 jds 54 *** created or updated.<br><br>
124 aw0a 1 *** Calling with mtx_ALL_BLOCKS is substantially more expensive
125     *** than calling with a specific block number if all you really
126 jds 54 *** want updated is a specific block.<br><br>
127 aw0a 1 ***
128 jds 54 *** Passes calls on slave matrices up to the master matrix.<br><br>
129 aw0a 1 ***
130     *** Returns 1 from a bad matrix, 2 from a bad bperm, 3 from a mismatch.
131 jds 54 *** Returns 0 from a successful call.<br><br>
132 aw0a 1 ***
133     -$- Does excessive checking, and then returns usual values if the
134     -$- corresponding excessive checks fail.
135     **/
136    
137 jds 54 extern int mtx_destroy_block_perm(mtx_block_perm_t bperm);
138 ben.allan 33 /**<
139 jds 54 *** <!-- mtx_destroy_block_perm(bperm); -->
140     *** <!-- mtx_block_perm_t bperm; -->
141 aw0a 1 ***
142     *** Deallocates all memory associated with the bperm.
143     *** Has nothing to do with the matrix of bperm's origin.
144     *** Returns 1 if anything untoward happens during the
145     *** destruction. Returns 0 otherwise.
146     **/
147    
148 jds 54 extern size_t mtx_block_perm_size(mtx_block_perm_t bperm);
149 ben.allan 33 /**<
150 jds 54 *** <!-- mtx_block_perm_size(bperm); -->
151     *** <!-- mtx_block_perm_t bperm; -->
152 aw0a 1 ***
153     *** One for the bean counters. Returns current memory used by
154     *** the mtx_block_perm_t. Bytes as usual.
155     **/
156    
157 jds 54 /* end block_perm functions */
158 aw0a 1
159 jds 54 /* ********************************************************************* *\
160 aw0a 1 mtx permutation and permutation info routines
161 jds 54 \* ********************************************************************* */
162     extern void mtx_swap_rows(mtx_matrix_t mtx, int32 row1, int32 row2);
163     /**<
164     *** Swaps two rows of the matrix. The association between the
165     *** "original row number" and the row contents is not
166     *** changed, so that some record is kept as to where a given row
167     *** originally came from (see mtx_org_to_row(), etc.).
168     ***
169     *** Passes calls on slave matrices up to the master matrix.
170     -$- Does nothing to a bad matrix.
171     **/
172 johnpye 522 ASC_DLLSPEC(void ) mtx_swap_cols(mtx_matrix_t mtx, int32 col1, int32 col2);
173 jds 54 /**<
174     *** Swaps two columns of the matrix. The association between the
175     *** "original column number" and the column contents is not
176     *** changed, so that some record is kept as to where a given column
177     *** originally came from (see mtx_org_to_row(), etc.).
178     ***
179     *** Passes calls on slave matrices up to the master matrix.
180     -$- Does nothing to a bad matrix.
181     **/
182     extern void mtx_drag(mtx_matrix_t mtx, int32 d1, int32 d2);
183     /**<
184     *** Drag shifts diagonal element d1 to position d2, or vice versa,
185     *** rotating all the intermediate elements as if d1 were swapped
186     *** (row and col) with all the intermediate di.<br><br>
187     *** Drag exists because it is twice the speed of the following
188     *** implementation outside of mtx: <pre>
189     *** while( n1 < n2 ) {
190     *** mtx_swap_rows(mtx,n1,n1+1);
191     *** mtx_swap_cols(mtx,n1,n1+1);
192     *** ++n1;
193     *** }
194     *** while( n1 > n2 ) {
195     *** mtx_swap_rows(mtx,n1,n1-1);
196     *** mtx_swap_cols(mtx,n1,n1-1);
197     *** --n1;
198     *** } </pre>
199     *** If it turns out that a cycle_col or cycle_row (independent of diagonal)
200     *** is wanted, implementation is now trivial.
201     ***
202     *** Passes calls on slave matrices up to the master matrix.
203     -$- Does nothing to a bad matrix.
204     **/
205     extern void mtx_reverse_diagonal(mtx_matrix_t mtx, int32 d1, int32 d2);
206     /**<
207     *** Does a series of symmetric permutations that reverses
208     *** the ordering of the diagonal between (and including) d1 & d2.
209     *** If d2 < d1, does nothing.
210     ***
211     *** Passes calls on slave matrices up to the master matrix.
212     -$- Does nothing to a bad matrix.
213     **/
214     /* OLD GROUP COMMENT */
215     /*
216 aw0a 1 -$- mtx_swap_rows(matrix,row1,row2)
217     -$- mtx_swap_cols(matrix,col1,col2)
218     -$- mtx_drag(matrix,d1,d2)
219     -$- mtx_reverse_diagonal(matrix,d1,d2)
220     *** mtx_matrix_t matrix;
221     *** int32 row1,row2;
222     *** int32 col1,col2;
223     *** int32 d1,d2;
224     ***
225     *** Swaps two rows/columns of the matrix. The association between the
226     *** "original row/column number" and the row/column contents is not
227     *** changed, so that some record is kept as to where a given row/column
228     *** originally came from (see mtx_org_to_row, etc.).
229     ***
230     *** Drag shifts diagonal element d1 to position d2, or vice versa,
231     *** rotating all the intermediate elements as if d1 were swapped
232     *** (row and col) with all the intermediate di.
233     *** Drag exists because it is twice the speed of the following
234     *** implementation outside of mtx:
235     *** while( n1 < n2 ) {
236     *** mtx_swap_rows(mtx,n1,n1+1);
237     *** mtx_swap_cols(mtx,n1,n1+1);
238     *** ++n1;
239     *** }
240     *** while( n1 > n2 ) {
241     *** mtx_swap_rows(mtx,n1,n1-1);
242     *** mtx_swap_cols(mtx,n1,n1-1);
243     *** --n1;
244     *** }
245     *** If it turns out that a cycle_col or cycle_row (independent of diagonal)
246     *** is wanted, implementation is now trivial.
247     ***
248     *** Reverse_diagonal does a series of symmetric permutations that reverses
249     *** the ordering of the diagonal between (and including) d1 & d2.
250     *** If d2 < d1, does nothing.
251     ***
252     *** All pass calls on slave matrices up to the master matrix.
253     ***
254     -$- Does nothing to a bad matrix.
255     **/
256    
257 johnpye 522 ASC_DLLSPEC(int32 ) mtx_row_to_org(mtx_matrix_t mtx, int32 row);
258 jds 54 /**<
259     *** Converts original row number <--> row number.
260     *** Passes calls on slave matrices up to the master matrix.
261     -$- Returns -1 from a bad matrix.
262     **/
263 johnpye 522 ASC_DLLSPEC(int32 ) mtx_col_to_org(mtx_matrix_t mtx, int32 col);
264 jds 54 /**<
265     *** Converts original column number <--> column number.
266     *** Passes calls on slave matrices up to the master matrix.
267     -$- Returns -1 from a bad matrix.
268     **/
269 johnpye 522 ASC_DLLSPEC(int32 ) mtx_org_to_row(mtx_matrix_t mtx, int32 orgrow);
270 jds 54 /**<
271     *** Converts original row number <--> row number.
272     *** Passes calls on slave matrices up to the master matrix.
273     -$- Returns -1 from a bad matrix.
274     **/
275 johnpye 522 ASC_DLLSPEC(int32 ) mtx_org_to_col(mtx_matrix_t mtx, int32 orgcol);
276 jds 54 /**<
277     *** Converts original column number <--> column number.
278     *** Passes calls on slave matrices up to the master matrix.
279     -$- Returns -1 from a bad matrix.
280     **/
281     /* OLD GROUP COMMENT */
282     /*
283 aw0a 1 -$- org_row = mtx_row_to_org(matrix,row)
284     -$- org_col = mtx_col_to_org(matrix,col)
285     -$- row = mtx_org_to_row(matrix,org_row)
286     -$- col = mtx_org_to_col(matrix,org_col)
287     *** int32 org_row,row,org_col,col;
288     *** mtx_matrix_t matrix;
289     ***
290     *** Converts original row number <--> row number, and original column
291     *** number <--> column number.
292     *** All pass calls on slave matrices up to the master matrix.
293     ***
294     -$- Returns -1 from a bad matrix.
295     **/
296    
297 jds 54 extern boolean mtx_row_parity(mtx_matrix_t mtx);
298     /**<
299     *** Returns the parity (even=FALSE,odd=TRUE) of the permutation which
300     *** carries original row to current row numbers.
301     *** Passes calls on slave matrices up to the master matrix.
302     -$- Returns -1 from a bad matrix.
303     **/
304     extern boolean mtx_col_parity(mtx_matrix_t mtx);
305     /**<
306     *** Returns the parity (even=FALSE,odd=TRUE) of the permutation which
307     *** carries original column to current column numbers.
308     *** Passes calls on slave matrices up to the master matrix.
309     -$- Returns -1 from a bad matrix.
310     **/
311     /* OLD GROUP COMMENT */
312     /*
313 aw0a 1 -$- parity = mtx_row_parity(matrix)
314     -$- parity = mtx_col_parity(matrix)
315     *** boolean parity;
316     *** mtx_matrix_t matrix;
317     ***
318     *** Returns the parity (even=FALSE,odd=TRUE) of the permutation which
319     *** carries original row/column to current row/column numbers.
320     *** All pass calls on slave matrices up to the master matrix.
321     ***
322     -$- Returns -1 from a bad matrix.
323     **/
324    
325 jds 54 /* ********************************************************************* *\
326 aw0a 1 mtx structural manipulation and info routines
327 jds 54 \* ********************************************************************* */
328 aw0a 1
329 jds 54 extern int mtx_output_assign_region(mtx_matrix_t mtx,
330     mtx_region_t *region,
331     int *orphaned_rows);
332     /**<
333     *** <!-- int rank = mtx_output_assign_region(matrix,region,orphaned_rows) -->
334     *** <!-- mtx_matrix_t matrix; -->
335     *** <!-- mtx_region_t *reg; -->
336     *** <!-- int orphaned_rows; -->
337 aw0a 1 ***
338     *** This function is very similar to its sister function mtx_output_assign.
339     *** It reorders the matrix to put as many non-zeros on the diagonal as
340     *** possible. It mtx_ENTIRE_MATRIX is sent in as the region, the output
341     *** assignment will affect the entire matrix. Otherwise the output
342     *** assignment will be restricted to the designated region.
343     *** This function returns the symbolic rank of the matrix. If a row can
344     *** not be assigned it is moved to the end of lower edge of the matrix.
345     *** The count of the unassigned aka orphaned rows is returned also.
346 jds 54 *** Unlike mtx_output_assign nothing else is done to the matrix.<br><br>
347 aw0a 1 ***
348     *** Calls on slaves are passed up to the master matrix.
349     ***
350     -$- Does nothing to a bad matrix.
351     **/
352    
353 jds 54 extern void mtx_output_assign(mtx_matrix_t mtx, int32 hirow, int32 hicol);
354     /**<
355     *** <!-- mtx_output_assign(matrix,hirow,hicol) -->
356     *** <!-- mtx_matrix_t matrix; -->
357     *** <!-- int32 hirow,hicol; -->
358     ***
359 aw0a 1 *** Reorders the matrix to put as many non-zeros on the diagonal as
360     *** possible. This function does not assume the validity of a previous
361     *** assignment. mtx_symbolic_rank() may be subsequently called to produce
362     *** the symbolic rank. All assigned rows and columns go into forming
363     *** a single initial block which is of dimension equal to the symbolic
364 jds 54 *** rank of the matrix.<br><br>
365 aw0a 1 ***
366     *** All unassigned rows and columns with incidence are then placed
367     *** against the borders of the nonsingular region while all empty rows
368     *** and columns are moved toward the outer borders of the matrix.
369     *** If hirow and hicol are not improperly small, we will guarantee that all
370     *** original rows r, 0 <= r < hirow, and original columns c,
371     *** 0 <= c < hicol, are placed next to the initial block. That is,
372     *** if that block is contained within the block ((0,0),(hirow,hicol)).
373     *** This is not a particularly interesting property mathematically, but
374     *** it makes things loads easier when writing interfaces that involve
375     *** mtx objects; the first hirow rows and hicol cols of the jacobian will
376     *** correspond to some relation or variable even if they haven't incidence.
377 jds 54 -$- Does nothing to a bad matrix.<br><br>
378 aw0a 1 *** NOTE:
379     *** When used on an incidence matrix, the fixed vars and unincluded
380     *** relations which don't generate elements may end up anywhere between
381     *** the initial block and the ends of the matrix if hirow and hicol are
382 jds 54 *** not specified correctly.<br><br>
383 aw0a 1 ***
384     *** Calls on slaves are passed up to the master matrix.
385     ***
386     *** Note that mtx_output_assign invalidates any data saved
387     *** with the mtx_*_block_perm functions.
388     **/
389    
390 johnpye 522 ASC_DLLSPEC(boolean ) mtx_output_assigned(mtx_matrix_t mtx);
391 ben.allan 33 /**<
392 jds 54 *** <!-- symbolic_rank_exists = mtx_output_assigned(matrix) -->
393     *** <!-- boolean symbolic_rank_exists; -->
394     *** <!-- mtx_matrix_t matrix; -->
395 aw0a 1 ***
396     *** Determines if the matrix has been previously output assigned.
397     *** Calls on slaves are passed up to the master matrix.
398     ***
399     -$- Returns FALSE on a bad matrix.
400     **/
401    
402 johnpye 522 ASC_DLLSPEC(int32 ) mtx_symbolic_rank(mtx_matrix_t mtx);
403 ben.allan 33 /**<
404 jds 54 *** <!-- symbolic_rank = mtx_symbolic_rank(matrix) -->
405     *** <!-- int32 symbolic_rank; -->
406     *** <!-- mtx_matrix_t matrix; -->
407 aw0a 1 ***
408     *** Returns the symbolic rank determined by a previous call to
409     *** mtx_output_assign().
410     *** Calls on slaves are passed up to the master matrix.
411     ***
412     -$- Returns -2 on bad matrix or -1 on unassigned one.
413     **/
414    
415 jds 54 extern void mtx_set_symbolic_rank(mtx_matrix_t mtx, int32 rank);
416 ben.allan 33 /**<
417 jds 54 *** <!-- mtx_symbolic_rank(matrix,rank) -->
418     *** <!-- int32 rank; -->
419     *** <!-- mtx_matrix_t matrix; -->
420 aw0a 1 ***
421     *** Sets symbolic rank of mtx. This is used in a hack
422     *** and is not intended for general use.
423     **/
424    
425 jds 54 extern boolean mtx_make_col_independent(mtx_matrix_t mtx,
426     int32 col,
427     mtx_range_t *rng);
428 ben.allan 33 /**<
429 jds 54 *** <!-- swapped = mtx_make_col_independent(matrix,col,rng) -->
430     *** <!-- boolean swapped; -->
431     *** <!-- mtx_matrix_t matrix; -->
432     *** <!-- int32 col; -->
433     *** <!-- mtx_range_t *rng; -->
434 aw0a 1 ***
435     *** Removes col from the basis in place of one of the columns in rng.
436     *** I.e. redoes the mtx_output_assign so as to not use col, if
437     *** possible, using one of the cols in rng instead.
438     *** Clears any prior partitioning data.
439     *** Note that mtx_make_col_independent invalidates any data saved
440 jds 54 *** with the mtx_*_block_perm functions.<br><br>
441 aw0a 1 ***
442     *** Calls on slaves are passed up to the master matrix.
443     **/
444    
445 jds 54 extern void mtx_org_permute(mtx_matrix_t mtx, mtx_region_t * region);
446 ben.allan 33 /**<
447 jds 54 *** <!-- mtx_org_permute(mtx,region); -->
448     *** <!-- mtx_matrix_t matrix; -->
449     *** <!-- mtx_region_t *region. -->
450     ***
451 aw0a 1 *** Given a region, repermutes rows and columns within it to the ordering
452     *** where mtx_row_to_org(mtx,i) < mtx_row_to_org(mtx,i+1) for all i and
453     *** where mtx_col_to_org(mtx,j) < mtx_row_to_org(mtx,j+1) for all j
454     *** within the region. At present this is implemented as a qsort and
455 jds 54 *** may be a little pricey.<br><br>
456 aw0a 1 ***
457     *** mtx_org_permute(mtx,mtx_ENTIRE_MATRIX); is equivalent to
458     *** mtx_reset_perm(mtx);
459     **/
460    
461 jds 54 extern int32 mtx_full_diagonal(mtx_matrix_t mtx, mtx_range_t *rng, int noisy);
462 ben.allan 33 /**<
463 jds 54 *** <!-- mtx_full_diagonal(mtx,rng,noisy); -->
464 aw0a 1 ***
465     *** This function checks the diagonal for holes. If symbolic_rank is
466     *** set, and rng->high < rank, returns immediately.
467     *** Returns number of holes detected in diagonal in rng given.
468     *** If noisy != 0, writes the hole locations to g_mtxerr.
469     *** On detectably bad input, returns -1.
470     *** Worst Cost: O(nnz) where nnz = incidence count sum over rows in rng.
471     *** Usual Cost: O(n) where n = a small factor *(rng->high - rng->low +1)
472     *** Does not pass calls up to master.
473     **/
474    
475 jds 54 extern int32 mtx_transpose(mtx_matrix_t mtx);
476 ben.allan 33 /**<
477 jds 54 *** <!-- mtx_transpose(mtx); -->
478 aw0a 1 *** Transposes everything about the matrix. The user is
479     *** responsible for keeping track of the change in the semantics
480 jds 54 *** this implies if the matrix is being used in a nonlinear context.<br><br>
481 aw0a 1 ***
482     *** Transposing a matrix also transposes all associated slave/master
483     *** matrices.
484 jds 54 *** To check if a matrix has been transposed, use mtx_isa_transpose.<br><br>
485 aw0a 1 *** Cost O(Nnz).
486     *** 0 order matrices cannot be transposed.
487     -$- Returns mtx_NONE on a bad or 0 order matrix.
488     **/
489    
490 jds 54 extern int32 mtx_isa_transpose(mtx_matrix_t mtx);
491 ben.allan 33 /**<
492 jds 54 *** <!-- mtx_isa_transpose(mtx); -->
493 aw0a 1 *** Returns 1 if the matrix is transposed from another and 0 if not.
494     *** Calling mtx_transpose twice yields a mtx which responds with 0.
495     -$- Returns mtx_NONE on a bad or 0 order matrix.
496     **/
497    
498 jds 54 /* ********************************************************************* *\
499 aw0a 1 Start of some block matrix routines. At the moment the block
500     structure is intimately tied up with the matrix.
501 jds 54 \* ********************************************************************* */
502 aw0a 1
503 jds 54 extern mtx_block_t *mtx_block_partition(mtx_matrix_t mtx, mtx_region_t *reg);
504 ben.allan 33 /**<
505 jds 54 *** <!-- mtx_partition(mtx,reg); -->
506     *** <!-- mtx_matrix_t matrix; -->
507     *** <!-- mtx_region_t *reg. -->
508 aw0a 1 ***
509     *** Partitions the single block of a previously output assigned matrix
510     *** into smaller blocks if possible. This function unlike its sister
511     *** mtx_partition, takes in, and returns information explicitly, rather
512     *** than assuming it to be a property of the matrix. The result will
513     *** be NULL, if there are no blocks. At the moment works only on
514     *** a square matrix. The range reg->row is assumed to represent the
515     *** extreme points of a square region. The caller owns the result and
516     *** must be deallocate it.
517     *** If the matrix given (or its master) is not assigned, this will
518     *** verify (at some expense) that the diagonal is full and whine
519 jds 54 *** if not. It will attempt to partition anyway assuming a diagonal.<br><br>
520 aw0a 1 ***
521     *** Calls on slaves are passed up to the master matrix.
522     **/
523    
524 jds 54 /* ********************************************************************* *\
525 aw0a 1 The original block manipulation routines.
526 jds 54 \* ********************************************************************* */
527 aw0a 1
528 jds 54 extern void mtx_partition(mtx_matrix_t mtx);
529 ben.allan 33 /**<
530 jds 54 *** <!-- mtx_partition(matrix); -->
531     *** <!-- mtx_matrix_t matrix; -->
532 aw0a 1 ***
533     *** Takes an output assigned matrix and does a permutation to
534 jds 54 *** block-lower-triangular form of the square region from
535     *** 0,0 to symbolic_rank-1, symbolic_rank-1.<br><br>
536     ***
537 aw0a 1 *** Calls on slaves are passed up to the master matrix.
538     **/
539    
540 jds 54 extern void mtx_ut_partition(mtx_matrix_t mtx);
541 ben.allan 33 /**<
542 jds 54 *** <!-- mtx_ut_partition(matrix); -->
543     *** <!-- mtx_matrix_t matrix; -->
544 aw0a 1 ***
545     *** Takes an output assigned matrix and does a permutation to
546 jds 54 *** block-UPPER-triangular form of the square region from
547     *** 0,0 to symbolic_rank-1, symbolic_rank-1.<br><br>
548     ***
549 aw0a 1 *** Calls on slaves are passed up to the master matrix.
550     **/
551    
552 jds 54 extern boolean mtx_check_blocks(mtx_matrix_t mtx);
553 ben.allan 33 /**<
554 jds 54 *** <!-- valid = mtx_check_blocks(matrix) -->
555     *** <!-- boolean valid; -->
556     *** <!-- mtx_matrix_t matrix; -->
557 aw0a 1 ***
558     *** Checks whether or not the block data are consistent with the
559     *** non-zero structure of the matrix. If not, the block data
560     *** are destroyed. Matrix must be previously output assigned,
561 jds 54 *** if not (or bad matrix) nothing is done.<br><br>
562 aw0a 1 ***
563     *** Calls on slaves are passed up to the master matrix.
564     **/
565    
566 jds 54 extern int32 mtx_number_of_blocks(mtx_matrix_t mtx);
567 ben.allan 33 /**<
568 aw0a 1 ***
569 jds 54 -$- <!-- nblocks = mtx_number_of_blocks(matrix) -->
570     *** <!-- int32 nblocks; -->
571     *** <!-- mtx_matrix_t matrix; -->
572 aw0a 1 ***
573     *** Returns the number of blocks in the matrix. Matrix must be
574     *** previously output assigned.
575     ***
576     *** Calls on slaves are passed up to the master matrix.
577     ***
578     -$- Returns mtx_NONE if matrix is bad which is liable to lead to core
579     -$- dumping if the user is not checking for a bad return.
580     **/
581    
582 jds 54 extern int32 mtx_block(mtx_matrix_t mtx,
583     int32 block_number,
584     mtx_region_t *block);
585     /**<
586     *** <!-- bndx = mtx_block(matrix,block_number,block) -->
587     *** <!-- mtx_matrix_t matrix; -->
588     *** <!-- int32 block_number; -->
589     *** <!-- mtx_region_t *block; -->
590 aw0a 1 ***
591     *** Sets block to the "block_number"-th block (indexed 0 to nblocks-1) in
592     *** the matrix. Matrix must be previously output assigned.
593     *** Returns mtx_NONE if not previously output assigned
594     *** or if requested block does not exist, or if no blocks exist,
595     *** otherwise returns 0.
596     *** If mtx_NONE is returned, block will contain the region
597 jds 54 *** ((0,order-1),(0,order-1)) where order is the mtx_order.<br><br>
598 aw0a 1 ***
599     *** Calls on slaves are passed up to the master matrix.
600     **/
601    
602 johnpye 522 ASC_DLLSPEC(int32 ) mtx_block_containing_row(mtx_matrix_t mtx,
603 jds 54 int32 row,
604     mtx_region_t *block);
605     /**<
606     *** Sets block to the block which contains the given row and
607     *** returns the block number. If the given row doesn't belong
608     *** to any block, mtx_NONE is returned. Matrix must be previously output
609     *** assigned or a 0 is returned.<br><br>
610     ***
611     *** Calls on slaves are passed up to the master matrix.
612     **/
613     extern int32 mtx_block_containing_col(mtx_matrix_t mtx,
614     int32 col,
615     mtx_region_t *block);
616     /**<
617     *** Sets block to the block which contains the given column and
618     *** returns the block number. If the given column doesn't belong
619     *** to any block, mtx_NONE is returned. Matrix must be previously output
620     *** assigned or a 0 is returned.<br><br>
621     ***
622     *** Calls on slaves are passed up to the master matrix.
623     **/
624     /* OLD GROUP COMMENT */
625     /*
626 aw0a 1 *** block_number = mtx_block_containing_row(matrix,row,block)
627     *** block_number = mtx_block_containing_col(matrix,col,block)
628     *** int32 block_number;
629     *** mtx_matrix_t matrix;
630     *** int32 row,col;
631     *** mtx_region_t *block;
632     ***
633     *** Sets block to the block which contains the given row/column and
634     *** returns the block number. If the given row/column doesn't belong
635     *** to any block, mtx_NONE is returned. Matrix must be previously output
636     *** assigned or a 0 is returned.
637     ***
638     *** Calls on slaves are passed up to the master matrix.
639     **/
640    
641 jds 54 #endif /* __MTX_PERMS_H_SEEN__ */

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