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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 522 - (show 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 /*
2 * 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
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 #ifndef __MTX_PERMS_H_SEEN__
40 #define __MTX_PERMS_H_SEEN__
41
42 /* the following block_perm functions are not yet implemented:
43 * this is the software spec. 5/3/95 baa. */
44
45 extern mtx_block_perm_t mtx_create_block_perm(mtx_matrix_t mtx);
46 /**<
47 *** <!-- bp = mtx_create_block_perm(mtx); -->
48 *** <!-- mtx_matrix_t mtx; -->
49 *** <!-- mtx_block_perm_t bp; -->
50 ***
51 *** 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 *** Returns NULL if a bad mtx is detected.<br><br>
60 ***
61 *** Passes calls on slave matrices up to the master matrix.<br><br>
62 ***
63 -$- Checks extra carefully for a bad matrix, and returns NULL if so.
64 **/
65
66 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 *** 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 *** bperm and the mtx. The mtx cannot have been resized.<br><br>
82 ***
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 *** nearly the size of the problem.<br><br>
89 ***
90 *** Passes calls on slave matrices up to the master matrix.<br><br>
91 ***
92 *** Returns 1 from a bad matrix, 2 from a bad bperm, 3 from a mismatch.
93 *** Returns 0 from a successful call.<br><br>
94 ***
95 -$- Does excessive result checking, and then returns 3 if the
96 -$- excessive checks fail.
97 **/
98
99 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 *** 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 *** if you try to do sneaky things, parity may get out of whack.<br><br>
117 ***
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 *** created or updated.<br><br>
124 *** Calling with mtx_ALL_BLOCKS is substantially more expensive
125 *** than calling with a specific block number if all you really
126 *** want updated is a specific block.<br><br>
127 ***
128 *** Passes calls on slave matrices up to the master matrix.<br><br>
129 ***
130 *** Returns 1 from a bad matrix, 2 from a bad bperm, 3 from a mismatch.
131 *** Returns 0 from a successful call.<br><br>
132 ***
133 -$- Does excessive checking, and then returns usual values if the
134 -$- corresponding excessive checks fail.
135 **/
136
137 extern int mtx_destroy_block_perm(mtx_block_perm_t bperm);
138 /**<
139 *** <!-- mtx_destroy_block_perm(bperm); -->
140 *** <!-- mtx_block_perm_t bperm; -->
141 ***
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 extern size_t mtx_block_perm_size(mtx_block_perm_t bperm);
149 /**<
150 *** <!-- mtx_block_perm_size(bperm); -->
151 *** <!-- mtx_block_perm_t bperm; -->
152 ***
153 *** One for the bean counters. Returns current memory used by
154 *** the mtx_block_perm_t. Bytes as usual.
155 **/
156
157 /* end block_perm functions */
158
159 /* ********************************************************************* *\
160 mtx permutation and permutation info routines
161 \* ********************************************************************* */
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 ASC_DLLSPEC(void ) mtx_swap_cols(mtx_matrix_t mtx, int32 col1, int32 col2);
173 /**<
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 -$- 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 ASC_DLLSPEC(int32 ) mtx_row_to_org(mtx_matrix_t mtx, int32 row);
258 /**<
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 ASC_DLLSPEC(int32 ) mtx_col_to_org(mtx_matrix_t mtx, int32 col);
264 /**<
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 ASC_DLLSPEC(int32 ) mtx_org_to_row(mtx_matrix_t mtx, int32 orgrow);
270 /**<
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 ASC_DLLSPEC(int32 ) mtx_org_to_col(mtx_matrix_t mtx, int32 orgcol);
276 /**<
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 -$- 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 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 -$- 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 /* ********************************************************************* *\
326 mtx structural manipulation and info routines
327 \* ********************************************************************* */
328
329 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 ***
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 *** Unlike mtx_output_assign nothing else is done to the matrix.<br><br>
347 ***
348 *** Calls on slaves are passed up to the master matrix.
349 ***
350 -$- Does nothing to a bad matrix.
351 **/
352
353 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 *** 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 *** rank of the matrix.<br><br>
365 ***
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 -$- Does nothing to a bad matrix.<br><br>
378 *** 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 *** not specified correctly.<br><br>
383 ***
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 ASC_DLLSPEC(boolean ) mtx_output_assigned(mtx_matrix_t mtx);
391 /**<
392 *** <!-- symbolic_rank_exists = mtx_output_assigned(matrix) -->
393 *** <!-- boolean symbolic_rank_exists; -->
394 *** <!-- mtx_matrix_t matrix; -->
395 ***
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 ASC_DLLSPEC(int32 ) mtx_symbolic_rank(mtx_matrix_t mtx);
403 /**<
404 *** <!-- symbolic_rank = mtx_symbolic_rank(matrix) -->
405 *** <!-- int32 symbolic_rank; -->
406 *** <!-- mtx_matrix_t matrix; -->
407 ***
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 extern void mtx_set_symbolic_rank(mtx_matrix_t mtx, int32 rank);
416 /**<
417 *** <!-- mtx_symbolic_rank(matrix,rank) -->
418 *** <!-- int32 rank; -->
419 *** <!-- mtx_matrix_t matrix; -->
420 ***
421 *** Sets symbolic rank of mtx. This is used in a hack
422 *** and is not intended for general use.
423 **/
424
425 extern boolean mtx_make_col_independent(mtx_matrix_t mtx,
426 int32 col,
427 mtx_range_t *rng);
428 /**<
429 *** <!-- 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 ***
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 *** with the mtx_*_block_perm functions.<br><br>
441 ***
442 *** Calls on slaves are passed up to the master matrix.
443 **/
444
445 extern void mtx_org_permute(mtx_matrix_t mtx, mtx_region_t * region);
446 /**<
447 *** <!-- mtx_org_permute(mtx,region); -->
448 *** <!-- mtx_matrix_t matrix; -->
449 *** <!-- mtx_region_t *region. -->
450 ***
451 *** 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 *** may be a little pricey.<br><br>
456 ***
457 *** mtx_org_permute(mtx,mtx_ENTIRE_MATRIX); is equivalent to
458 *** mtx_reset_perm(mtx);
459 **/
460
461 extern int32 mtx_full_diagonal(mtx_matrix_t mtx, mtx_range_t *rng, int noisy);
462 /**<
463 *** <!-- mtx_full_diagonal(mtx,rng,noisy); -->
464 ***
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 extern int32 mtx_transpose(mtx_matrix_t mtx);
476 /**<
477 *** <!-- mtx_transpose(mtx); -->
478 *** Transposes everything about the matrix. The user is
479 *** responsible for keeping track of the change in the semantics
480 *** this implies if the matrix is being used in a nonlinear context.<br><br>
481 ***
482 *** Transposing a matrix also transposes all associated slave/master
483 *** matrices.
484 *** To check if a matrix has been transposed, use mtx_isa_transpose.<br><br>
485 *** Cost O(Nnz).
486 *** 0 order matrices cannot be transposed.
487 -$- Returns mtx_NONE on a bad or 0 order matrix.
488 **/
489
490 extern int32 mtx_isa_transpose(mtx_matrix_t mtx);
491 /**<
492 *** <!-- mtx_isa_transpose(mtx); -->
493 *** 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 /* ********************************************************************* *\
499 Start of some block matrix routines. At the moment the block
500 structure is intimately tied up with the matrix.
501 \* ********************************************************************* */
502
503 extern mtx_block_t *mtx_block_partition(mtx_matrix_t mtx, mtx_region_t *reg);
504 /**<
505 *** <!-- mtx_partition(mtx,reg); -->
506 *** <!-- mtx_matrix_t matrix; -->
507 *** <!-- mtx_region_t *reg. -->
508 ***
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 *** if not. It will attempt to partition anyway assuming a diagonal.<br><br>
520 ***
521 *** Calls on slaves are passed up to the master matrix.
522 **/
523
524 /* ********************************************************************* *\
525 The original block manipulation routines.
526 \* ********************************************************************* */
527
528 extern void mtx_partition(mtx_matrix_t mtx);
529 /**<
530 *** <!-- mtx_partition(matrix); -->
531 *** <!-- mtx_matrix_t matrix; -->
532 ***
533 *** Takes an output assigned matrix and does a permutation to
534 *** block-lower-triangular form of the square region from
535 *** 0,0 to symbolic_rank-1, symbolic_rank-1.<br><br>
536 ***
537 *** Calls on slaves are passed up to the master matrix.
538 **/
539
540 extern void mtx_ut_partition(mtx_matrix_t mtx);
541 /**<
542 *** <!-- mtx_ut_partition(matrix); -->
543 *** <!-- mtx_matrix_t matrix; -->
544 ***
545 *** Takes an output assigned matrix and does a permutation to
546 *** block-UPPER-triangular form of the square region from
547 *** 0,0 to symbolic_rank-1, symbolic_rank-1.<br><br>
548 ***
549 *** Calls on slaves are passed up to the master matrix.
550 **/
551
552 extern boolean mtx_check_blocks(mtx_matrix_t mtx);
553 /**<
554 *** <!-- valid = mtx_check_blocks(matrix) -->
555 *** <!-- boolean valid; -->
556 *** <!-- mtx_matrix_t matrix; -->
557 ***
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 *** if not (or bad matrix) nothing is done.<br><br>
562 ***
563 *** Calls on slaves are passed up to the master matrix.
564 **/
565
566 extern int32 mtx_number_of_blocks(mtx_matrix_t mtx);
567 /**<
568 ***
569 -$- <!-- nblocks = mtx_number_of_blocks(matrix) -->
570 *** <!-- int32 nblocks; -->
571 *** <!-- mtx_matrix_t matrix; -->
572 ***
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 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 ***
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 *** ((0,order-1),(0,order-1)) where order is the mtx_order.<br><br>
598 ***
599 *** Calls on slaves are passed up to the master matrix.
600 **/
601
602 ASC_DLLSPEC(int32 ) mtx_block_containing_row(mtx_matrix_t mtx,
603 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 *** 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 #endif /* __MTX_PERMS_H_SEEN__ */

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