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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 592 - (show annotations) (download) (as text)
Fri May 12 09:50:57 2006 UTC (14 years, 8 months ago) by johnpye
File MIME type: text/x-chdr
File size: 85270 byte(s)
Working on adding some more export symbols, for purpose of getting Jerry's test suite to work with SCons build.
1 /*
2 * mtx2: 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.13 $
7 * Version control file: $RCSfile: mtx_basic.h,v $
8 * Date last modified: $Date: 2000/01/25 02:27:10 $
9 * Last modified by: $Author: ballan $
10 *
11 * This file is part of the SLV solver.
12 *
13 * Copyright (C) 1990 Karl Michael Westerberg
14 * Copyright (C) 1993 Joseph Zaher
15 * Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan
16 * Copyright (C) 1995 Benjamin Andrew Allan, Kirk Andre' Abbott
17 * Copyright (C) 1996 Benjamin Andrew Allan
18 *
19 * The SLV solver is free software; you can redistribute
20 * it and/or modify it under the terms of the GNU General Public License as
21 * published by the Free Software Foundation; either version 2 of the
22 * License, or (at your option) any later version.
23 *
24 * The SLV solver is distributed in hope that it will be
25 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
26 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
27 * General Public License for more details.
28 *
29 * You should have received a copy of the GNU General Public License along with
30 * the program; if not, write to the Free Software Foundation, Inc., 675
31 * Mass Ave, Cambridge, MA 02139 USA. Check the file named COPYING.
32 * COPYING is found in ../compiler.
33 */
34
35 /** @file
36 * mtx2: Ascend Sparse Matrix Package.
37 * <pre>
38 * requires: #include "utilities/ascConfig.h"
39 * requires: #include "mtx.h"
40 * </pre>
41 */
42
43 #ifndef __MTX_BASIC_H_SEEN__
44 #define __MTX_BASIC_H_SEEN__
45
46 /***********************************************************************\
47 mtx types creation/destruction/info routines
48 \***********************************************************************/
49 extern boolean check_matrix(mtx_matrix_t mtx, char *file, int line);
50 /**<
51 * Implementation function for mtx_check_matrix().
52 * Do not call this function directly - use mtx_check_matrix() instead.
53 * @todo check_matrix() should return TRUE/FALSE, not 1/0.
54 */
55 #define mtx_check_matrix(mtx) check_matrix((mtx),__FILE__,__LINE__)
56 /**<
57 ** <!-- (mtx_matrix_t, char *, int); -->
58 **
59 ** <!-- Use mtx_check_matrix in all cases. -->
60 ** <!-- If mtx given is ok, returns 1, otherwise returns 0. -->
61 ** <!-- spits up to stderr if not ok. -->
62 ** <!-- If mtx is a slave, also checks integrity on the master mtx. -->
63 <!-- mm macro extern boolean mtx_check_matrix(m) -->
64 ** Checks the integrity flag of the matrix.
65 ** Returns 1 if mtx is ok (non-NULL, integrity flag ok).
66 ** Otherwise returns 0. If mtx is not ok, a message is
67 ** printed to g_mtxerr. If mtx is a slave, the integrity
68 ** on the master mtx is also checked.
69 ** @param mtx mtx_matrix_t, the matrix to check.
70 ** @return 1 if given matrix is valid, 0 otherwise.
71 **/
72
73 extern boolean check_sparse(const mtx_sparse_t * const sp,
74 char *file, int line);
75 /**<
76 * Implementation function for mtx_check_sparse().
77 * Do not call this function directly - use mtx_check_sparse() instead.
78 * @todo check_sparse() should return TRUE/FALSE, not 1/0.
79 */
80 #define mtx_check_sparse(sp) check_sparse((sp),__FILE__,__LINE__)
81 /**<
82 * <!-- (mtx_sparse_t *, char *, int); -->
83 **
84 ** <!-- Use mtx_check_sparse in all cases. -->
85 ** <!-- If sparse given is ok, returns 1, otherwise returns 0. -->
86 ** <!-- spits up to stderr if not ok. -->
87 <!-- mm macro extern boolean mtx_check_sparse(sp) -->
88 ** Checks the consistency of a sparse matrix as best it can.
89 ** Returns 1 if sp is ok, FALSE if something wierd is found.
90 ** If sp is not ok, a message is printed to g_mtxerr.
91 ** @param sp const mtx_sparse_t * const, the sparse matrix to check.
92 ** @return 1 if given matrix is valid, 0 otherwise.
93 **/
94
95 ASC_DLLSPEC(mtx_coord_t *) mtx_coord(mtx_coord_t *coordp, int32 row, int32 col);
96 /**<
97 *** Places the values of row and col into coordp and returns
98 *** the coordp pointer again.
99 ***
100 *** Typical usage: <pre>
101 *** {
102 *** mtx_coord_t coord;
103 *** value = mtx_value(matrix,mtx_coord(&coord,row,col));
104 *** } </pre>
105 **/
106 extern mtx_range_t *mtx_range(mtx_range_t *rangep, int32 low, int32 high);
107 /**<
108 *** Places the values of low and high into rangep and returns
109 *** the rangep pointer again.
110 **/
111 ASC_DLLSPEC(mtx_region_t *) mtx_region(mtx_region_t *regionp,
112 int32 rowlow, int32 rowhigh,
113 int32 collow, int32 colhigh);
114 /**<
115 *** <!-- coordp = mtx_coord(coordp,row,col) -->
116 *** <!-- rangep = mtx_range(rangep,low,high) -->
117 *** <!-- regionp = mtx_region(regionp,rowlow,rowhigh,collow,colhigh)-->
118 *** <!-- mtx_coord_t *coordp; -->
119 *** <!-- mtx_range_t *rangep; -->
120 *** <!-- mtx_region_t *regionp; -->
121 *** <!-- int32 row,col,low,high,rowlow,rowhigh,collow,colhigh; -->
122 ***
123 *** <!-- Places the values of arguments 2,3,... into the structure p-->ointed to
124 *** <!-- by argument 1 and returns the pointer to it again. -->
125 ***
126 *** <!-- Typical usage: -->
127 *** <!-- { -->
128 *** <!-- mtx_coord_t coord; -->
129 *** <!-- value = mtx_value(matrix,mtx_coord(&coord,row,col)); -->
130 *** <!-- } -->
131 *** Places the ranges specified by (rowlow,rowhigh) and
132 *** (collow,colhigh) into regionp and returns the
133 *** regionp pointer again.
134 **/
135
136 ASC_DLLSPEC(void ) mtx_zero_int32(int32 *data, int len);
137 /**< Zeros an int32 vector of specified length. Ignores NULL input vectors. */
138 extern void mtx_zero_real64(real64 *data, int len);
139 /**< Zeros a real64 vector of specified length. Ignores NULL input vectors. */
140 extern void mtx_zero_ptr(void **data, int len);
141 /**< Zeros a vector of pointers of specified length. Ignores NULL input vectors. */
142 #define mtx_zero_char(ar,len) if ((ar)!=NULL) memset((ar),0,(len))
143 /**<
144 *** <!-- mtx_zero_XXX(ptr,length); -->
145 *** <!-- Zeros a vector of specified length and type. -->
146 *** <!-- Ignore NULL input vectors. -->
147 *** Zeros a char vector of specified length. Ignores NULL input vectors.
148 **/
149
150 ASC_DLLSPEC(mtx_matrix_t) mtx_create(void);
151 /**<
152 *** <!-- matrix = mtx_create() -->
153 *** <!-- mtx_matrix_t matrix; -->
154 ***
155 *** Creates a 0-order matrix and returns a handle to it.
156 *** Matrix created is a master with no slaves.
157 **/
158
159 extern mtx_matrix_t mtx_create_slave(mtx_matrix_t master);
160 /**<
161 *** <!-- matrix = mtx_create_slave(master) -->
162 *** <!-- mtx_matrix_t matrix, master; -->
163 ***
164 *** Create and return a matrix which shares all structural
165 *** information EXCEPT incidence pattern/values with the
166 *** master matrix given. A master may have as many slaves
167 *** as desired. Slaves cannot have slaves. Slaves cannot
168 *** become masters. Copies of slave matrices are totally
169 *** independent of both slave and master.<br><br>
170 ***
171 *** All structural manipulation/query function calls will
172 *** be passed up to the master. When the master is resized,
173 *** all its slaves are resized.<br><br>
174 ***
175 *** This function will return NULL if called on a matrix which
176 *** is a slave or otherwise bad.<br><br>
177 ***
178 *** Slave matrices exist to:
179 *** - Let the user keep a whole stack of matrices in permutation
180 *** synchrony for the price of structural operations on only
181 *** the master matrix. Principally, this reduces mtx_drag cost.
182 *** - Reduce the memory overhead of a matrix duplicate
183 *** when the duplicate is to be kept in structural synchrony.
184 *** The additional memory required to maintain a slave matrix
185 *** is the cost of the incidence stored in the slave plus
186 *** 2*mtx_capacity(master)*sizeof(double) + sizeof(void *).
187 *** - Demonstrate that C can knock the cookies out of FORTRAN
188 *** in speed while delivering twice the semantic content
189 *** in the output of a matrix factorization routine.
190 **/
191
192 extern void mtx_debug_redirect_freeze(void);
193 /**<
194 *** Stops future mtx_create()/mtx_create_slave() from
195 *** redirecting errors back to stderr.
196 **/
197
198 ASC_DLLSPEC(void) mtx_destroy(mtx_matrix_t matrix);
199 /**<
200 *** <!-- mtx_destroy(matrix); -->
201 *** <!-- mtx_matrix_t matrix; -->
202 ***
203 *** Destroys the matrix, freeing the memory it occupied.
204 *** Does nothing if matrix fails mtx_check_matrix.
205 *** Destroys all slaves associated with the matrix if
206 *** it is a master. If mtx is a slave, its master must
207 *** also pass check_matrix before slave is destroyed.
208 **/
209
210 extern mtx_sparse_t *mtx_create_sparse(int32 capacity);
211 /**<
212 *** <!-- sp = mtx_create_sparse(capacity); -->
213 *** <!-- mtx_sparse_t *sp; -->
214 *** <!-- int32 capacity; -->
215 ***
216 *** Creates a sparse vector with capacity given and returns it.
217 *** The length of the sparse data is initialized to 0.
218 *** If insufficient memory is available, returns NULL.
219 **/
220
221 ASC_DLLSPEC(void ) mtx_destroy_sparse(mtx_sparse_t *sp);
222 /**<
223 *** <!-- mtx_destroy_sparse(sp); -->
224 *** <!-- mtx_sparse_t *sp; -->
225 ***
226 *** Given a pointer to the sparse structure, deallocates everything to
227 *** do with the structure, including the structure itself. The pointer
228 *** sp is invalidated. Handles NULL gracefully.
229 **/
230
231 extern void mtx_destroy_blocklist(mtx_block_t *bl);
232 /**<
233 *** <!-- mtx_destroy_blocklist); -->
234 *** <!-- mtx_block_t *bl; -->
235 ***
236 *** Given a pointer to the block structure, deallocates everything to
237 *** do with the structure, including the structure itself. The pointer
238 *** bl is invalidated. Handles NULL gracefully.
239 *** If nblocks is 0 and the region array is not, region pointer will be
240 *** abandoned.
241 **/
242
243 extern mtx_matrix_t mtx_duplicate_region(mtx_matrix_t matrix,
244 mtx_region_t *region,
245 real64 drop);
246 /**<
247 -$- <!-- slave = mtx_duplicate_region(matrix,region,drop); -->
248 ***
249 *** <!-- mtx_matrix_t slave, matrix; -->
250 *** <!-- mtx_region_t *region; -->
251 *** <!-- real64 drop; -->
252 ***
253 *** Creates a slave of the matrix given (or of the master of the matrix
254 *** given). This operator provides a low overhead way of
255 *** saving a matrix region for later computation. The slave matrix
256 *** returned is kept permuted to the same ordering as the master from
257 *** which it was created.<br><br>
258 ***
259 *** The incidence is copied from the matrix given, even if the matrix
260 *** given is the slave of another matrix. During the copy, all Aij such
261 *** that abs(Aij) < drop in the matrix given are ignored.<br><br>
262 ***
263 *** If you want a slave but do not want to copy any incidence, you should
264 *** just use mtx_create_slave(matrix); instead.<br><br>
265 ***
266 -$- Does nothing if matrix fails mtx_check_matrix; returns NULL.
267 **/
268
269 extern mtx_matrix_t mtx_copy_options(mtx_matrix_t matrix,
270 boolean blocks, boolean incidence,
271 mtx_region_t *region, real64 drop);
272 /**<
273 -$- <!-- copy = mtx_copy_options(matrix,blocks,incidence,region,drop-->);
274 ***
275 *** General matrix copy function.
276 *** All operations can take either a master or a slave matrix
277 *** and all return a NEW master. If you want a slave copy, see
278 *** mtx_duplicate_region.<br><br>
279 ***
280 *** This function should generally be considered an implementation
281 *** function not to be called directly. Use one of the macros described
282 *** below to perform the type of copy desired.
283 ***
284 *** <!-- MACROS: -->
285 -$- <!-- copy = mtx_copy(matrix) -->
286 -$- <!-- copy = mtx_copy_region(matrix,region) -->
287 -$- <!-- copy = mtx_copy_region_drop(matrix,region,drop) -->
288 -$- <!-- copy = mtx_copy_wo_incidence(matrix) -->
289 -$- <!-- copy = mtx_copy_complete(matrix) -->
290 *** <!-- mtx_matrix_t copy,matrix; -->
291 *** <!-- boolean blocks, incidence; -->
292 *** <!-- mtx_region_t *region; -->
293 *** <!-- real64 drop; -->
294 *** <pre>
295 *** mtx_copy_complete(mtx)
296 *** Copies everything to do with a mtx. Copying the block information
297 *** is usually redundant because the caller should use the block info
298 *** from the original matrix, but in the odd event that such is not
299 *** the case, we provide the copy_complete operator.
300 *** Note that if you are copying a matrix created by mtx_copy
301 *** or mtx_copy_wo_incidence then the copy returned will not have
302 *** block data.
303 ***
304 *** mtx_copy(mtx)
305 *** Copies the matrix except for the block structure and returns
306 *** a handle to the new copy. Most commonly used.
307 ***
308 *** mtx_copy_region(matrix,region)
309 *** Copies the matrix excluding the block structure and any
310 *** incidence outside the region given.
311 ***
312 *** mtx_copy_region_drop(matrix,region,drop)
313 *** As mtx_copy_region(), except that incidence of magnitude < abs(drop) is
314 *** not copied. Note that in C 0.0 !< 0.0. Use a really small number if
315 *** you want 0s suppressed in the copy.
316 ***
317 *** mtx_copy_wo_incidence(mtx)
318 *** Copies the matrix except for the nonzero and block structure
319 *** and returns a handle to the new copy. If you find yourself
320 *** doing mtx_copy followed by mtx_clear, use this instead.<br><br>
321 ***
322 -$- Does nothing if matrix fails mtx_check_matrix; returns NULL.
323 *** </pre>
324 <!-- mmm macro extern mtx_matrix_t mtx_copy(m) -->
325 <!-- mmm macro extern mtx_matrix_t mtx_copy_region(m,r) -->
326 <!-- mmm macro extern mtx_matrix_t mtx_copy_region_drop(m,r,d) -->
327 <!-- mmm macro extern mtx_matrix_t mtx_copy_wo_incidence(m) -->
328 <!-- mmm macro extern mtx_matrix_t mtx_copy_complete(m) -->
329 **/
330 #define mtx_copy(m) mtx_copy_options((m),FALSE,TRUE,mtx_ENTIRE_MATRIX,0.0)
331 /**< See mtx_copy_options(). */
332 #define mtx_copy_region(m,r) mtx_copy_options((m),FALSE,TRUE,(r),0.0)
333 /**< See mtx_copy_options(). */
334 #define mtx_copy_region_drop(m,r,d) mtx_copy_options((m),FALSE,TRUE,(r),(d))
335 /**< See mtx_copy_options(). */
336 #define mtx_copy_wo_incidence(m) mtx_copy_options((m),FALSE,FALSE,NULL,0.0)
337 /**< See mtx_copy_options(). */
338 #define mtx_copy_complete(m) mtx_copy_options((m),TRUE,TRUE, mtx_ENTIRE_MATRIX,0.0)
339 /**< See mtx_copy_options(). */
340
341 ASC_DLLSPEC(int32 ) mtx_order(mtx_matrix_t matrix);
342 /**<
343 *** <!-- order = mtx_order(matrix) -->
344 *** <!-- int32 order; -->
345 *** <!-- mtx_matrix_t matrix; -->
346 ***
347 *** Returns the order of the matrix, be it master or slave.
348 -$- Order of a corrupt matrix is -1;
349 **/
350
351 ASC_DLLSPEC(int32 ) mtx_capacity(mtx_matrix_t matrix);
352 /**<
353 *** <!-- cap = mtx_capacity(matrix) -->
354 *** <!-- int32 cap; -->
355 *** <!-- mtx_matrix_t matrix; -->
356 ***
357 *** Returns the capacity of the matrix, be it master or slave.
358 *** Original row/column numbers must lie in the range 0 <= ndx < cap.
359 *** cap may be larger than the matrix order if the order of the matrix
360 *** was ever at time higher than it is now.
361 -$- capacity of a corrupt matrix is -1;
362 **/
363
364 ASC_DLLSPEC(void) mtx_set_order(mtx_matrix_t matrix, int32 order);
365 /**<
366 *** <!-- mtx_set_order(matrix,order) -->
367 *** <!-- mtx_matrix_t matrix; -->
368 *** <!-- int32 order; -->
369 ***
370 *** Changes the order of the matrix to the new order, either truncating
371 *** the matrix, or extending it with blank rows and columns if necessary.
372 *** Does not change the incidence pattern if the matrix is being expanded.
373 *** Calls on slaves are passed up to the master. Calls on a master reset
374 *** the order for all of its slaves.
375 ***
376 *** @bug This should return a memory allocation status boolean,
377 *** but doesn't. Does nothing to a bad matrix.
378 **/
379
380 extern void mtx_clear_coord(mtx_matrix_t matrix, int32 row, int32 col);
381 /**<
382 *** Erase an element in a matrix. The specified element must
383 *** exist to be erased.
384 -$- Does nothing to a bad matrix if MTX_DEBUG is defined.
385 *** Will work as usual on masters/slaves.
386 *** @see mtx_clear() for more about matrix clearing functions.
387 **/
388
389 extern void mtx_clear_row(mtx_matrix_t matrix, int32 row, mtx_range_t *rng);
390 /**<
391 *** Erase a range of elements in a single row of a matrix.
392 -$- Does nothing to a bad matrix if MTX_DEBUG is defined.
393 *** Will work as usual on masters/slaves.
394 *** @see mtx_clear() for more about matrix clearing functions.
395 **/
396
397 extern void mtx_clear_col(mtx_matrix_t matrix,int32 col, mtx_range_t *rng);
398 /**<
399 *** Erase a range of elements in a single column of a matrix.
400 -$- Does nothing to a bad matrix if MTX_DEBUG is defined.
401 *** Will work as usual on masters/slaves.
402 *** @see mtx_clear() for more about matrix clearing functions.
403 **/
404
405 extern void mtx_clear_rowlist(mtx_matrix_t matrix,
406 mtx_sparse_t *sp, mtx_range_t *rng);
407 /**<
408 *** NOT IMPLEMENTED.
409 *** Erase a range of elements in the list of rows given in
410 *** the idata of the sparse. The data of the sparse need not
411 *** be valid as it will not be referenced.
412 -$- Does nothing to a bad matrix if MTX_DEBUG is defined.
413 *** Will work as usual on masters/slaves.
414 *** @see mtx_clear() for more about matrix clearing functions.
415 **/
416
417 extern void mtx_clear_collist(mtx_matrix_t matrix,
418 mtx_sparse_t *sp, mtx_range_t *rng);
419 /**<
420 *** NOT IMPLEMENTED.
421 *** Erase a range of elements in the list of columns given in
422 *** the idata of the sparse. The data of the sparse need not
423 *** be valid as it will not be referenced.
424 -$- Does nothing to a bad matrix if MTX_DEBUG is defined.
425 *** Will work as usual on masters/slaves.
426 *** @see mtx_clear() for more about matrix clearing functions.
427 **/
428
429 ASC_DLLSPEC(void ) mtx_clear_region(mtx_matrix_t matrix, mtx_region_t *region);
430 /**<
431 *** Erases all elements in the given region.
432 -$- Does nothing to a bad matrix if MTX_DEBUG is defined.<br><br>
433 *** mtx_clear_region(slave,region) can be used without affecting other
434 *** slaves or the master.
435 *** mtx_clear_region(master,region) affects only the master UNLESS
436 *** region is mtx_ENTIRE_MATRIX. mtx_ENTIRE_MATRIX clears the master
437 *** and ALL incidence in ALL its slaves.
438 *** @see mtx_clear() for more about matrix clearing functions.
439 **/
440
441 extern void mtx_reset_perm(mtx_matrix_t matrix);
442 /**<
443 *** Restores the original row/column ordering.
444 -$- Does nothing to a bad matrix if MTX_DEBUG is defined.<br><br>
445 *** Note that mtx_reset_perm() invalidates any data saved with
446 *** the mtx_*_block_perm functions.<br><br>
447 *** mtx_reset_perm(master or slave) passes the reset up to the master.
448 *** @see mtx_clear() for more about matrix clearing functions.
449 **/
450
451 ASC_DLLSPEC(void) mtx_clear(mtx_matrix_t matrix);
452 /**<
453 *** Clears everything in the matrix.
454 -$- Does nothing to a bad matrix if MTX_DEBUG is defined.<br><br>
455 ***
456 *** It is generally most efficient to clear as many incidences in possible
457 *** in a single call. When a set of adjacent rows/columns is to be cleared,
458 *** use mtx_clear_region. If a rather disjoint set is to be cleared (such
459 *** as the nonlinear rows of a mixed linear/nonlinear jacobian) use
460 *** mtx_clear_rowlist/collist.<br><br>
461 ***
462 *** Note that mtx_clear() invalidates any data saved with the
463 *** mtx_*_block_perm functions.<br><br>
464 *** mtx_clear(master or slave) passes up to the master.
465 **/
466 /* OLD GROUP COMMENT */
467 /*
468 -$- mtx_clear_coord(matrix,row,col)
469 -$- mtx_clear_row(matrix,row,rng)
470 -$- mtx_clear_col(matrix,col,rng)
471 -$- mtx_clear_rowlist(matrix,sp,rng) !* not yet implemented *!
472 -$- mtx_clear_collist(matrix,sp,rng) !* not yet implemented *!
473 -$- mtx_clear_region(matrix,region)
474 -$- mtx_reset_perm(matrix)
475 -$- mtx_clear(matrix)
476 *** mtx_matrix_t matrix;
477 *** mtx_sparse_t *sp;
478 *** mtx_region_t *region;
479 *** mtx_range_t *rowrng;
480 ***
481 *** mtx_clear_coord will make sure a specific element doesn't exist.
482 *** mtx_clear_row and mtx_clear_col will erase a range of elements
483 *** in a single row or column.
484 *** mtx_clear_rowlist and mtx_clear_collist will erase a range of elements
485 *** in the list of rows or columns given in the idata of the sparse.
486 *** The data of the sparse need not be valid as it will not be referenced.
487 *** mtx_clear_region erases all elements in the given region.
488 *** mtx_reset_perm restores the original row/column ordering.
489 *** mtx_clear clears everything.
490 -$- Does nothing to a bad matrix.
491 ***
492 *** It is generally most efficient to clear as many incidences in possible
493 *** in a single call. When a set of adjacent rows/columns is to be cleared,
494 *** use mtx_clear_region. If a rather disjoint set is to be cleared (such
495 *** as the nonlinear rows of a mixed linear/nonlinear jacobian) use
496 *** mtx_clear_rowlist/collist.
497 ***
498 *** Note that mtx_clear and mtx_reset_perm invalidate any data saved
499 *** with the mtx_*_block_perm functions.
500 *** Notes on masters/slaves:
501 *** mtx_clear_coord, mtx_clear_row, mtx_clear_col, mtx_clear_rowlist,
502 *** mtx_clear_collist work as usual.
503 *** mtx_clear_region(slave,region) can be used without affecting other
504 *** slaves or the master.
505 *** mtx_clear_region(master,region) affects only the master UNLESS
506 *** region is mtx_ENTIRE_MATRIX. mtx_ENTIRE_MATRIX clears the master
507 *** and ALL incidence in ALL its slaves.
508 *** mtx_reset_perm(master or slave) passes the reset up to the master.
509 *** mtx_clear(master or slave) passes up to the master.
510 ***
511 *** Clears everything in the matrix.
512 -$- Does nothing to a bad matrix if MTX_DEBUG is defined.<br><br>
513 ***
514 *** It is generally most efficient to clear as many incidences in possible
515 *** in a single call. When a set of adjacent rows/columns is to be cleared,
516 *** use mtx_clear_region. If a rather disjoint set is to be cleared (such
517 *** as the nonlinear rows of a mixed linear/nonlinear jacobian) use
518 *** mtx_clear_rowlist/collist.<br><br>
519 ***
520 *** Note that mtx_clear() invalidates any data saved with the
521 *** mtx_*_block_perm functions.<br><br>
522 *** mtx_clear(master or slave) passes up to the master.
523 **/
524
525 extern real64 mtx_value(mtx_matrix_t matrix, mtx_coord_t *coord);
526 /**<
527 ***
528 *** Use of mtx_value() should be avoided if at all possible
529 *** inside loops. See mtx_next_in_* for doing mtx/vector operations.
530 *** Returns the value of the given element in the matrix.
531 *** Doesn't matter whether a matrix is slave or master.
532 -$- Returns 0.0/does nothing from/to a bad matrix.
533 **/
534
535 extern void mtx_set_value(mtx_matrix_t matrix,
536 mtx_coord_t *coord, real64 value);
537 /**<
538 *** Sets the value of the given element in the matrix.
539 *** Because the only sane usage of mtx_set_value() is for
540 *** things like setting something in the diagonal,
541 *** mtx_set_value() remembers the last place mtx_value() returned
542 *** and checks it before starting a search. Any element destruction
543 *** causes mtx_set_value() to forget, however.
544 *** This remembrance is matrix specific and is not affected by
545 *** element destruction in other unrelated matrices.
546 *** Like mtx_value(), use of mtx_set_value() should be avoided if at
547 *** all possible inside loops. See mtx_next_in_* for doing mtx/vector
548 *** operations.<br><br>
549 ***
550 *** mtx_set_value(mtx,coord,0.0) will create no incidence if none
551 *** is presently there, nor does it delete an incidence.
552 ***
553 *** Doesn't matter whether a matrix is slave or master.
554 ***
555 -$- Returns 0.0/does nothing from/to a bad matrix.
556 *** @see mtx_fill_value()
557 **/
558
559 ASC_DLLSPEC(void) mtx_fill_value(mtx_matrix_t matrix,
560 mtx_coord_t *coord, real64 value);
561 /**<
562 *** Sets the value of the given element in the matrix.
563 *** Use this function in place of mtx_set_value() in those instances
564 *** where the caller knows there currently exists no element at the
565 *** coordinate whose value is to be set. mtx_fill_value() can also be
566 *** used if a mtx_assemble() call will happen before ANY other numeric
567 *** or structural calls are made.
568 ***
569 *** Doesn't matter whether a matrix is slave or master.
570 ***
571 -$- Returns 0.0/does nothing from/to a bad matrix.
572 *** @see mtx_fill_org_value()
573 **/
574
575 extern void mtx_fill_org_value(mtx_matrix_t matrix,
576 const mtx_coord_t *coord,
577 real64 value);
578 /**<
579 *** Sets the value of the given element in the matrix.
580 *** This function is just like mtx_fill_value() except the location
581 *** given is understood as the (orgrow,orgcol) location to put the fill.
582 ***
583 *** Doesn't matter whether a matrix is slave or master.
584 ***
585 -$- Returns 0.0/does nothing from/to a bad matrix.
586 **/
587 /* OLD GROUP COMMENT */
588 /*
589 -$- value = mtx_value(matrix,coord)
590 -$- mtx_set_value(matrix,coord,value)
591 -$- mtx_fill_value(matrix,coord,value)
592 -$- mtx_fill_org_value(matrix,orgcoord,value)
593 *** real64 value;
594 *** mtx_matrix_t matrix;
595 *** mtx_coord_t *coord, *orgcoord;
596 ***
597 *** Use of mtx_value, mtx_set_value should be avoided if at all possible
598 *** inside loops. See mtx_next_in_* for doing mtx/vector operations.
599 *** Returns/sets the value of the given element in the matrix.
600 *** Because the only sane usage of mtx_value, mtx_set_value is for
601 *** things like getting and setting something in the diagonal,
602 *** mtx_set_value remembers the last place mtx_value returned
603 *** and checks it before starting a search. Any element destruction
604 *** causes mtx_set_value to forget, however.
605 *** This remembrance is matrix specific and is not affected by
606 *** element destruction in other unrelated matrices.
607 ***
608 *** mtx_fill_value is
609 *** to be used in place of mtx_set_value in those instances where the
610 *** caller knows there currently exists no element at the coordinate
611 *** whose value is to be set. mtx_fill_value can also be used if a
612 *** mtx_assemble call will happen before ANY other numeric or structural
613 *** calls are made.
614 ***
615 *** mtx_fill_org_value is
616 *** just like mtx_fill_value except the location given is understood as
617 *** the (orgrow,orgcol) location to put the fill.
618 ***
619 *** mtx_set_value(mtx,coord,0.0) will create no incidence if none
620 *** is presently there, nor does it delete an incidence.
621 ***
622 *** Doesn't matter whether a matrix is slave or master.
623 ***
624 -$- Returns 0.0/does nothing from/to a bad matrix.
625 ***
626 *** Sets the value of the given element in the matrix.
627 *** This function is just like mtx_fill_value() except the location
628 *** given is understood as the (orgrow,orgcol) location to put the fill.
629 ***
630 *** Doesn't matter whether a matrix is slave or master.
631 ***
632 -$- Returns 0.0/does nothing from/to a bad matrix.
633 **/
634
635 /** grandfathering old linsol. @todo Remove when linsolqr replaces linsol. */
636 #define mtx_add_value(a,b,c) mtx_fill_value((a),(b),(c))
637
638 extern int32 mtx_assemble(mtx_matrix_t matrix);
639 /**<
640 *** <!-- dinc = mtx_assemble(mtx_matrix_t matrix); -->
641 *** <!-- mtx_matrix_t matrix; -->
642 *** <!-- int32 dinc; -->
643 ***
644 *** Takes a matrix, assumed to have redundant and otherwise insane incidences
645 *** created by mtx_fill_value and sums all like entries, eliminating
646 *** the duplicates and the zeroes. Returns -# of duplicate elements removed.
647 *** returns 1 if fails for some reason.
648 *** @todo Could stand to have the error messages it emits improved.
649 *** @todo Could stand to take a rowrange or a rowlist,
650 *** a colrange or a collist,droptol.
651 *** Zeroes are not counted as duplicates.
652 *** algorithm cost: O(3*nnz)
653 **/
654
655 /* ********************************************************************* *\
656 mtx element routines
657 None of these routines care about master/slave status.
658 \* ********************************************************************* */
659
660 extern void mtx_del_zr_in_row(mtx_matrix_t matrix, int32 row);
661 /**<
662 *** "Non-zeros" in the given row which are actually
663 *** zero are effectively removed (i.e. the status of "non-zero" is revoked).
664 -$- Does nothing to a bad matrix.
665 **/
666 extern void mtx_del_zr_in_col(mtx_matrix_t matrix, int32 col);
667 /**<
668 *** "Non-zeros" in the given col which are actually
669 *** zero are effectively removed (i.e. the status of "non-zero" is revoked).
670 -$- Does nothing to a bad matrix.
671 **/
672 extern void mtx_del_zr_in_rowrange(mtx_matrix_t matrix, mtx_range_t *rng);
673 /**<
674 *** "Non-zeros" in the given range of rows which are actually
675 *** zero are effectively removed (i.e. the status of "non-zero" is revoked).
676 -$- Does nothing to a bad matrix.
677 **/
678 extern void mtx_del_zr_in_colrange(mtx_matrix_t matrix, mtx_range_t *rng);
679 /**<
680 *** "Non-zeros" in the given range of cols which are actually
681 *** zero are effectively removed (i.e. the status of "non-zero" is revoked).
682 -$- Does nothing to a bad matrix.
683 **/
684 /* OLD GROUP COMMENT */
685 /*
686 -$- mtx_del_zr_in_row(matrix,row)
687 -$- mtx_del_zr_in_col(matrix,col)
688 -$- mtx_del_zr_in_rowrange(matrix,rng)
689 -$- mtx_del_zr_in_colrange(matrix,rng)
690 *** mtx_matrix_t matrix;
691 *** int32 row,col;
692 *** mtx_range_t *rng;
693 ***
694 *** "Non-zeros" in the given row/col/rng of rows/cols which are actually
695 *** zero are effectively removed (i.e. the status of "non-zero" is revoked).
696 -$- Does nothing to a bad matrix.
697 **/
698
699 extern void mtx_steal_org_row_vec(mtx_matrix_t mtx, int32 row,
700 real64 *vec, mtx_range_t *colrng);
701 /**<
702 *** The user is expected to supply the vec; we cannot check it.
703 *** Copies the mtx nonzeros currently within colrng INTO array vec which is
704 *** indexed by org column number. Does not affect other
705 *** entries of vec in or outside the range. In particular, vec
706 *** is NOT zeroed within the range unless there is a matrix element
707 *** with value zero at that location.
708 *** All incidence within colrng of the row given is removed from the matrix.<br><br>
709 ***
710 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
711 *** the row/col of interest is known to have incidence exclusively in
712 *** the range of interest.<br><br>
713 ***
714 -$- Fetches nothing from a bad matrix.
715 **/
716 extern void mtx_steal_org_col_vec(mtx_matrix_t mtx, int32 col,
717 real64 *vec, mtx_range_t *rowrng);
718 /**<
719 *** The user is expected to supply the vec; we cannot check it.
720 *** Copies the mtx nonzeros currently within rowrng INTO array vec which is
721 *** indexed by org row number. Does not affect other
722 *** entries of vec in or outside the range. In particular, vec
723 *** is NOT zeroed within the range unless there is a matrix element
724 *** with value zero at that location.
725 *** All incidence within rowrng of the col given is removed from the matrix.<br><br>
726 ***
727 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
728 *** the row/col of interest is known to have incidence exclusively in
729 *** the range of interest.<br><br>
730 ***
731 -$- Fetches nothing from a bad matrix.
732 **/
733 extern void mtx_steal_cur_row_vec(mtx_matrix_t mtx, int32 row,
734 real64 *vec, mtx_range_t *colrng);
735 /**<
736 *** The user is expected to supply the vec; we cannot check it.
737 *** Copies the mtx nonzeros currently within colrng INTO array vec which is
738 *** indexed by cur column number. Does not affect other
739 *** entries of vec in or outside the range. In particular, vec
740 *** is NOT zeroed within the range unless there is a matrix element
741 *** with value zero at that location.
742 *** All incidence within colrng of the row given is removed from the matrix.<br><br>
743 ***
744 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
745 *** the row/col of interest is known to have incidence exclusively in
746 *** the range of interest.<br><br>
747 ***
748 -$- Fetches nothing from a bad matrix.
749 **/
750 extern void mtx_steal_cur_col_vec(mtx_matrix_t mtx, int32 col,
751 real64 *vec, mtx_range_t *rowrng);
752 /**<
753 *** The user is expected to supply the vec; we cannot check it.
754 *** Copies the mtx nonzeros currently within rowrng INTO array vec which is
755 *** indexed by cur row number. Does not affect other
756 *** entries of vec in or outside the range. In particular, vec
757 *** is NOT zeroed within the range unless there is a matrix element
758 *** with value zero at that location.
759 *** All incidence within rowrng of the col given is removed from the matrix.<br><br>
760 ***
761 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
762 *** the row/col of interest is known to have incidence exclusively in
763 *** the range of interest.<br><br>
764 ***
765 -$- Fetches nothing from a bad matrix.
766 **/
767 /* OLD GROUP COMMENT */
768 /*
769 -$- mtx_steal_org_row_vec(mtx,row,vec,colrng)
770 -$- mtx_steal_org_col_vec(mtx,col,vec,rowrng)
771 -$- mtx_steal_cur_row_vec(mtx,row,vec,colrng)
772 -$- mtx_steal_cur_col_vec(mtx,col,vec,rowrng)
773 *** mtx_matrix_t mtx;
774 *** int32 row,col;
775 *** real64 *vec;
776 *** mtx_range_t *colrng,*rowrng;
777 ***
778 *** mtx_steal_org/cur_row_vec:
779 *** The user is expected to supply the vec; we cannot check it.
780 *** Copies the mtx nonzeros currently within colrng INTO array vec which is
781 *** indexed by org/cur column number. Does not affect other
782 *** entries of vec in or outside the range. In particular, vec
783 *** is NOT zeroed within the range unless there is a matrix element
784 *** with value zero at that location.
785 *** All incidence within colrng of the row given is removed from the matrix.
786 ***
787 *** mtx_steal_org/cur_col_vec:
788 *** Switch row <--> col in above.
789 ***
790 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
791 *** the row/col of interest is known to have incidence exclusively in
792 *** the range of interest.
793 ***
794 -$- Fetches nothing from a bad matrix.
795 **/
796
797 /*****************************************************************\
798 Sparse vector operations, rather analogous to the mtx_value suite.
799 These are tools for data motion. No arithmetic operators
800 are provided as yet. The deallocation of sparse vectors is
801 the user's job. See the notes at the top of this header for the
802 data semantics of a sparse vector.
803 The user may construct a sparse vector.
804 Calls which return a sparse vector may create or use and return
805 a user supplied sparse vector. These calls are at liberty to
806 reallocate the data memory if that supplied is insufficient to
807 hold the data. The len and cap values of the vector will be reset
808 as appropriate.
809
810 Functions do not create a sparse unless it says in their header
811 that mtx_CREATE_SPARSE is a valid argument.
812 \*****************************************************************/
813
814 extern boolean mtx_steal_org_row_sparse(mtx_matrix_t mtx,
815 int32 row,
816 mtx_sparse_t *sparse,
817 mtx_range_t *colrng);
818 /**<
819 *** Copies the mtx nonzeros currently within colrng to the sparse,
820 *** indexing by org column number. Nonzeros with value 0.0 WILL NOT
821 *** be included in the sparse. sparse->len will be set accordingly.
822 *** All incidence within colrng will be deleted from the mtx.<br><br>
823 ***
824 *** The user must supply the sparse; if it is too small, err will be
825 *** TRUE and data will not be collected and incidence not cleared.
826 *** mtx_CREATE_SPARSE is not a valid argument to this function.
827 *** What is too small? For all flavors the sparse must
828 *** have at least the capacity indicated by the col/rowrng.<br><br>
829 ***
830 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
831 *** the row/col of interest is known to have incidence exclusively in
832 *** the range of interest.<br><br>
833 ***
834 -$- Fetches nothing from a bad matrix.
835 **/
836 extern boolean mtx_steal_org_col_sparse(mtx_matrix_t mtx,
837 int32 col,
838 mtx_sparse_t *sparse,
839 mtx_range_t *rowrng);
840 /**<
841 *** Copies the mtx nonzeros currently within rowrng to the sparse,
842 *** indexing by org rowumn number. Nonzeros with value 0.0 WILL NOT
843 *** be included in the sparse. sparse->len will be set accordingly.
844 *** All incidence within rowrng will be deleted from the mtx.<br><br>
845 ***
846 *** The user must supply the sparse; if it is too small, err will be
847 *** TRUE and data will not be collected and incidence not cleared.
848 *** mtx_CREATE_SPARSE is not a valid argument to this function.
849 *** What is too small? For all flavors the sparse must
850 *** have at least the capacity indicated by the row/colrng.<br><br>
851 ***
852 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
853 *** the row/col of interest is known to have incidence exclusively in
854 *** the range of interest.<br><br>
855 ***
856 -$- Fetches nothing from a bad matrix.
857 **/
858 extern boolean mtx_steal_cur_row_sparse(mtx_matrix_t mtx,
859 int32 row,
860 mtx_sparse_t *sparse,
861 mtx_range_t *colrng);
862 /**<
863 *** Copies the mtx nonzeros currently within colrng to the sparse,
864 *** indexing by cur column number. Nonzeros with value 0.0 WILL NOT
865 *** be included in the sparse. sparse->len will be set accordingly.
866 *** All incidence within colrng will be deleted from the mtx.<br><br>
867 ***
868 *** The user must supply the sparse; if it is too small, err will be
869 *** TRUE and data will not be collected and incidence not cleared.
870 *** mtx_CREATE_SPARSE is not a valid argument to this function.
871 *** What is too small? For all flavors the sparse must
872 *** have at least the capacity indicated by the col/rowrng.<br><br>
873 ***
874 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
875 *** the row/col of interest is known to have incidence exclusively in
876 *** the range of interest.<br><br>
877 ***
878 -$- Fetches nothing from a bad matrix.
879 **/
880 extern boolean mtx_steal_cur_col_sparse(mtx_matrix_t mtx,
881 int32 col,
882 mtx_sparse_t *sparse,
883 mtx_range_t *rowrng);
884 /**<
885 *** Copies the mtx nonzeros currently within rowrng to the sparse,
886 *** indexing by cur rowumn number. Nonzeros with value 0.0 WILL NOT
887 *** be included in the sparse. sparse->len will be set accordingly.
888 *** All incidence within rowrng will be deleted from the mtx.<br><br>
889 ***
890 *** The user must supply the sparse; if it is too small, err will be
891 *** TRUE and data will not be collected and incidence not cleared.
892 *** mtx_CREATE_SPARSE is not a valid argument to this function.
893 *** What is too small? For all flavors the sparse must
894 *** have at least the capacity indicated by the row/colrng.<br><br>
895 ***
896 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
897 *** the row/col of interest is known to have incidence exclusively in
898 *** the range of interest.<br><br>
899 ***
900 -$- Fetches nothing from a bad matrix.
901 **/
902 /* OLD GROUP COMMENT */
903 /*
904 -$- err = mtx_steal_org_row_sparse(mtx,row,sparse,colrng)
905 -$- err = mtx_steal_org_col_sparse(mtx,col,sparse,rowrng)
906 -$- err = mtx_steal_cur_row_sparse(mtx,row,sparse,colrng)
907 -$- err = mtx_steal_cur_col_sparse(mtx,col,sparse,rowrng)
908 *** mtx_matrix_t mtx;
909 *** int32 row,col;
910 *** mtx_sparse_t *sparse;
911 *** mtx_range_t *colrng,*rowrng;
912 *** boolean err;
913 ***
914 *** The user must supply the sparse; if it is too small, err will be
915 *** TRUE and data will not be collected and incidence not cleared.
916 *** mtx_CREATE_SPARSE is not a valid argument to this function.
917 *** What is too small? For all flavors the sparse must
918 *** have at least the capacity indicated by the col/rowrng.
919 ***
920 *** mtx_steal_org/cur_row_sparse:
921 *** Copies the mtx nonzeros currently within colrng to the sparse,
922 *** indexing by org/cur column number. Nonzeros with value 0.0 WILL NOT
923 *** be included in the sparse. sparse->len will be set accordingly.
924 *** All incidence within colrng will be deleted from the mtx.
925 ***
926 *** mtx_steal_org/cur_col_sparse:
927 *** Switch row < col in above.
928 ***
929 *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when
930 *** the row/col of interest is known to have incidence exclusively in
931 *** the range of interest.
932 ***
933 -$- Fetches nothing from a bad matrix.
934 **/
935
936 /*
937 extern wish ! ! ! NOT YET IMPLEMENTED. NO USE FOR THEM SO FAR.
938 extern void ! ! ! mtx_set_org_row_vec(mtx_matrix_t, int32,
939 real64 *, mtx_range_t *,boolean);
940 extern void ! ! ! mtx_set_org_col_vec(mtx_matrix_t, int32,
941 real64 *, mtx_range_t *,boolean);
942 extern void ! ! ! mtx_set_cur_row_vec(mtx_matrix_t, int32,
943 real64 *, mtx_range_t *,boolean);
944 extern void ! ! ! mtx_set_cur_col_vec(mtx_matrix_t, int32,
945 real64 *, mtx_range_t *,boolean);
946 -$- mtx_set_org_row_vec(mtx,row,vec,colrng,destructive)
947 -$- mtx_set_org_col_vec(mtx,col,vec,rowrng,destructive)
948 -$- mtx_set_cur_row_vec(mtx,row,vec,colrng,destructive)
949 -$- mtx_set_cur_col_vec(mtx,col,vec,rowrng,destructive)
950 *** mtx_matrix_t mtx;
951 *** int32 row,col;
952 *** real64 *vec;
953 *** mtx_range_t *colrng,*rowrng;
954 *** boolean destructive;
955 ***
956 *** mtx_set_org/cur_row_vec:
957 *** Copies the nonzeros currently within colrng FROM array vec which is
958 *** indexed by org/cur column number INTO the matrix.
959 *** If destructive is TRUE, existing nonzeros which are given value 0.0
960 ***
961 *** mtx_set_org/cur_col_vec:
962 *** Switch row <--> col in above.
963 ***
964 *** Notes: It is faster to call this with a narrow range than with
965 *** mtx_ALL_COLS/ROWS. For ranges with very low sparsity, it may
966 *** be faster to call mtx_clear_row/col followed by mtx_fill_*_*_vec,
967 *** depending on the time cost of allocating and deallocating small
968 *** pieces of memory on the machine in question.
969 ***
970 ! ! Warning: If destructive is TRUE, care should be taken when using
971 ! ! these operators within a mtx_next_in_* loop that the current element
972 ! ! of the loop is not zeroed by the vec causing it to be deallocated.
973 ***
974 -$- Puts nothing to a bad matrix.
975 **/
976
977 extern void mtx_fill_org_row_vec(mtx_matrix_t mtx, int32 row,
978 real64 *vec, mtx_range_t *colrng);
979 /**<
980 *** Assumes that the colrng of row in the matrix is empty and
981 *** copies the nonzeros currently within colrng FROM array vec which is
982 *** indexed by org column number INTO the matrix.<br><br>
983 ***
984 *** Notes: It is faster to call this with a narrow range than with
985 *** mtx_ALL_COLS/ROWS. It is very marginally faster to call
986 *** mtx_fill_cur_row_vec() instead of this function.<br><br>
987 ! ! If you use this when the range is NOT empty, you will sooner or
988 ! ! later certainly lose numerical integrity and you may lose memory
989 ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br>
990 ***
991 -$- Puts nothing to a bad matrix.
992 **/
993 extern void mtx_fill_org_col_vec(mtx_matrix_t mtx, int32 col,
994 real64 *vec, mtx_range_t *rowrng);
995 /**<
996 *** Assumes that the rowrng of col in the matrix is empty and
997 *** copies the nonzeros currently within rowrng FROM array vec which is
998 *** indexed by org row number INTO the matrix.
999 ***
1000 *** Notes: It is faster to call this with a narrow range than with
1001 *** mtx_ALL_COLS/ROWS. It is very marginally faster to call
1002 *** mtx_fill_cur_col_vec() than this function.<br><br>
1003 ! ! If you use this when the range is NOT empty, you will sooner or
1004 ! ! later certainly lose numerical integrity and you may lose memory
1005 ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br>
1006 ***
1007 -$- Puts nothing to a bad matrix.
1008 **/
1009 extern void mtx_fill_cur_row_vec(mtx_matrix_t mtx, int32 row,
1010 real64 *vec, mtx_range_t *colrng);
1011 /**<
1012 *** Assumes that the colrng of row in the matrix is empty and
1013 *** copies the nonzeros currently within colrng FROM array vec which is
1014 *** indexed by cur column number INTO the matrix.<br><br>
1015 ***
1016 *** Notes: It is faster to call this with a narrow range than with
1017 *** mtx_ALL_COLS/ROWS. It is very marginally faster to call
1018 *** this function instead of mtx_fill_org_row_vec().<br><br>
1019 ! ! If you use this when the range is NOT empty, you will sooner or
1020 ! ! later certainly lose numerical integrity and you may lose memory
1021 ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br>
1022 ***
1023 -$- Puts nothing to a bad matrix.
1024 **/
1025 extern void mtx_fill_cur_col_vec(mtx_matrix_t mtx, int32 col,
1026 real64 *vec, mtx_range_t *rowrng);
1027 /**<
1028 *** Assumes that the rowrng of col in the matrix is empty and
1029 *** copies the nonzeros currently within rowrng FROM array vec which is
1030 *** indexed by cur row number INTO the matrix.
1031 ***
1032 *** Notes: It is faster to call this with a narrow range than with
1033 *** mtx_ALL_COLS/ROWS. It is very marginally faster to call
1034 *** this functions instead of mtx_fill_org_col_vec().<br><br>
1035 ! ! If you use this when the range is NOT empty, you will sooner or
1036 ! ! later certainly lose numerical integrity and you may lose memory
1037 ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br>
1038 ***
1039 -$- Puts nothing to a bad matrix.
1040 **/
1041 extern void mtx_dropfill_cur_row_vec(mtx_matrix_t mtx, int32 row,
1042 real64 *vec, mtx_range_t *colrng,
1043 real64 tolerance);
1044 /**<
1045 *** Assumes that the colrng of row in the matrix is empty and
1046 *** copies the values such that abs(value) >tolerance currently
1047 *** within colrng FROM array vec which is
1048 *** indexed by cur row number INTO the matrix.<br><br>
1049 ***
1050 *** Notes: It is faster to call this with a narrow range than with
1051 *** mtx_ALL_COLS/ROWS.
1052 ! ! If you use this when the range is NOT empty, you will sooner or
1053 ! ! later certainly lose numerical integrity and you may lose memory
1054 ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br>
1055 ***
1056 -$- Puts nothing to a bad matrix.
1057 **/
1058 extern void mtx_dropfill_cur_col_vec(mtx_matrix_t mtx, int32 col,
1059 real64 *vec, mtx_range_t *rowrng,
1060 real64 tolerance);
1061 /**<
1062 *** Assumes that the rowrng of col in the matrix is empty and
1063 *** copies the values such that abs(value) >tolerance currently
1064 *** within rowrng FROM array vec which is
1065 *** indexed by cur column number INTO the matrix.<br><br>
1066 ***
1067 *** Notes: It is faster to call this with a narrow range than with
1068 *** mtx_ALL_COLS/ROWS.
1069 ! ! If you use this when the range is NOT empty, you will sooner or
1070 ! ! later certainly lose numerical integrity and you may lose memory
1071 ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br>
1072 ***
1073 -$- Puts nothing to a bad matrix.
1074 **/
1075 /* OLD GROUP COMMENT */
1076 /*
1077 -$- mtx_fill_org_row_vec(mtx,row,vec,colrng)
1078 -$- mtx_fill_org_col_vec(mtx,col,vec,rowrng)
1079 -$- mtx_fill_cur_row_vec(mtx,row,vec,colrng)
1080 -$- mtx_fill_cur_col_vec(mtx,col,vec,rowrng)
1081 -$- mtx_dropfill_cur_row_vec(mtx,row,vec,colrng,tolerance)
1082 -$- mtx_dropfill_cur_col_vec(mtx,col,vec,rowrng,tolerance)
1083 *** mtx_matrix_t mtx;
1084 *** int32 row, col;
1085 *** real64 tolerance, *vec;
1086 *** mtx_range_t *colrng, *rowrng;
1087 ***
1088 *** mtx_fill_org/cur_row_vec:
1089 *** Assumes that the colrng of row in the matrix is empty and
1090 *** copies the nonzeros currently within colrng FROM array vec which is
1091 *** indexed by org/cur column number INTO the matrix.
1092 ***
1093 *** mtx_fill_org/cur_col_vec:
1094 *** Switch row < col in above.
1095 ***
1096 *** mtx_dropfill_cur_row/col_vec:
1097 *** Assumes that the colrng of row in the matrix is empty and
1098 *** copies the values such that abs(value) >tolerance currently
1099 *** within colrng FROM array vec which is
1100 *** indexed by cur column/row number INTO the matrix.
1101 ***
1102 *** Notes: It is faster to call these with a narrow range than with
1103 *** mtx_ALL_COLS/ROWS. It is very marginally faster to call the cur
1104 *** rather than the org flavor of these functions.
1105 ! ! If you use this when the range is NOT empty, you will sooner or
1106 ! ! later certainly lose numerical integrity and you may lose memory
1107 ! ! integrity. The sparse matrix programmer cannot afford to be naive.
1108 ***
1109 -$- Puts nothing to a bad matrix.
1110 **/
1111
1112 extern void mtx_fill_org_row_sparse(mtx_matrix_t mtx, int32 row,
1113 const mtx_sparse_t *sparse);
1114 /**<
1115 *** Fills the current row given with the data in the sparse given.
1116 *** The indices in sp->idata are taken as org col indices.
1117 *** It is assumed that the row is empty, at least where data is
1118 *** being added.<br><br>
1119 ***
1120 *** This function ignores 0.0 in the data and does not create numbers
1121 *** there in the mtx.
1122 **/
1123 extern void mtx_fill_org_col_sparse(mtx_matrix_t mtx, int32 col,
1124 const mtx_sparse_t *sparse);
1125 /**<
1126 *** Fills the current col given with the data in the sparse given.
1127 *** The indices in sp->idata are taken as org row indices.
1128 *** It is assumed that the col is empty, at least where data is
1129 *** being added.<br><br>
1130 ***
1131 *** This function ignores 0.0 in the data and does not create numbers
1132 *** there in the mtx.
1133 **/
1134 extern void mtx_fill_cur_row_sparse(mtx_matrix_t mtx, int32 row,
1135 const mtx_sparse_t *sparse);
1136 /**<
1137 *** Fills the current row given with the data in the sparse given.
1138 *** The indices in sp->idata are taken as cur col indices.
1139 *** It is assumed that the row is empty, at least where data is
1140 *** being added.<br><br>
1141 ***
1142 *** This function ignores 0.0 in the data and does not create numbers
1143 *** there in the mtx.
1144 **/
1145 extern void mtx_fill_cur_col_sparse(mtx_matrix_t mtx, int32 col,
1146 const mtx_sparse_t *sparse);
1147 /**<
1148 *** Fills the current col given with the data in the sparse given.
1149 *** The indices in sp->idata are taken as cur row indices.
1150 *** It is assumed that the col is empty, at least where data is
1151 *** being added.<br><br>
1152 ***
1153 *** This function ignores 0.0 in the data and does not create numbers
1154 *** there in the mtx.
1155 **/
1156 /* OLD GROUP COMMENT */
1157 /*
1158 -$- mtx_fill_org_row_sparse(mtx,row,sp)
1159 -$- mtx_fill_org_col_sparse(mtx,col,sp)
1160 -$- mtx_fill_cur_row_sparse(mtx,row,sp)
1161 -$- mtx_fill_cur_col_sparse(mtx,col,sp)
1162 *** mtx_matrix_t mtx;
1163 *** int32 row, col;
1164 *** mtx_sparse_t *sp;
1165 ***
1166 *** mtx_fill_org_row_sparse:
1167 *** Fills the current row given with the data in the sparse given.
1168 *** The indices in sp->idata are taken as org col indices.
1169 *** It is assumed that the row is empty, at least where data is
1170 *** being added.
1171 *** mtx_fill_org_col_sparse:
1172 *** Swap row/col in the previous description.
1173 ***
1174 *** mtx_fill_cur_row_sparse:
1175 *** Fills the current row given with the data in the sparse given.
1176 *** The indices in sp->idata are taken as cur col indices.
1177 *** It is assumed that the row is empty, at least where data is
1178 *** being added.
1179 *** mtx_fill_cur_col_sparse:
1180 *** Swap row/col in the previous description.
1181 ***
1182 *** All these functions ignore 0.0 in the data and do not create numbers
1183 *** there in the mtx.
1184 **/
1185
1186
1187 extern void mtx_mult_row(mtx_matrix_t mtx, int32 row,
1188 real64 factor, mtx_range_t *colrng);
1189 /**<
1190 *** Multiplies the given row by a given factor. Only those
1191 *** elements with column index within the given range are multiplied.
1192 *** This function tests for factor=0.0 and blows away the row if true.
1193 -$- Does nothing on a bad matrix.
1194 **/
1195 extern void mtx_mult_col(mtx_matrix_t mtx, int32 col,
1196 real64 factor, mtx_range_t *rowrng);
1197 /**<
1198 *** Multiplies the given column by a given factor. Only those
1199 *** elements with row index within the given range are multiplied.
1200 *** This function tests for factor=0.0 and blows away the row if true.
1201 -$- Does nothing on a bad matrix.
1202 **/
1203 extern void mtx_mult_row_zero(mtx_matrix_t mtx, int32 row,
1204 mtx_range_t *colrng);
1205 /**<
1206 *** Zeros the given row. Only those
1207 *** elements with column index within the given range are zeroed.
1208 *** This function zeros without disturbing structure.
1209 -$- Does nothing on a bad matrix.
1210 **/
1211 extern void mtx_mult_col_zero(mtx_matrix_t mtx, int32 col,
1212 mtx_range_t *rowrng);
1213 /**<
1214 *** Zeros the given column. Only those
1215 *** elements with row index within the given range are zeroed.
1216 *** This function zeros without disturbing structure.
1217 -$- Does nothing on a bad matrix.
1218 **/
1219 /* OLD GROUP COMMENT */
1220 /*
1221 -$- mtx_mult_row(matrix,row,factor,colrng)
1222 -$- mtx_mult_col(matrix,col,factor,rowrng)
1223 -$- mtx_mult_row_zero(matrix,row,colrng)
1224 -$- mtx_mult_col_zero(matrix,col,rowrng)
1225 *** mtx_matrix_t matrix;
1226 *** int32 row,col;
1227 *** real64 factor;
1228 *** mtx_range_t *colrng,*rowrng;
1229 ***
1230 *** Multiplies the given row/column by a given factor. Only those
1231 *** elements with column/row index within the given range are multiplied.
1232 *** mtx_mult_row/col tests for factor=0.0 and blows away the row if true.
1233 *** mtx_mult_row/col_zero zeros without disturbing structure.
1234 -$- Does nothing on a bad matrix.
1235 **/
1236
1237 extern void mtx_add_row(mtx_matrix_t mtx, int32 srow, int32 trow,
1238 real64 factor, mtx_range_t *colrng);
1239 /**<
1240 *** Adds a given multiple of row srow to row trow.
1241 *** Only those elements with column index within the given range are
1242 *** so affected.<br><br>
1243 -$- Does nothing on a bad matrix.
1244 **/
1245 extern void mtx_add_col(mtx_matrix_t mtx, int32 scol, int32 tcol,
1246 real64 factor, mtx_range_t *rowrng);
1247 /**<
1248 *** Adds a given multiple of column scol to column tcol.
1249 *** Only those elements with row index within the given range are
1250 *** so affected.<br><br>
1251 -$- Does nothing on a bad matrix.
1252 **/
1253 /* OLD GROUP COMMENT */
1254 /*
1255 -$- mtx_add_row(matrix,srow,trow,factor,colrng)
1256 -$- mtx_add_col(matrix,scol,tcol,factor,rowrng)
1257 *** mtx_matrix_t matrix;
1258 *** int32 srow,trow,scol,tcol;
1259 *** real64 factor;
1260 *** mtx_range_t *colrng,*rowrng;
1261 ***
1262 *** Adds a given multiple of row srow/column scol to row trow/column tcol.
1263 *** Only those elements with column/row index within the given range are
1264 *** so affected.
1265 -$- Does nothing on a bad matrix.
1266 **/
1267
1268 extern void mtx_add_row_series(int32 srow, real64 factor,
1269 mtx_range_t *colrng);
1270 /**<
1271 *** Adds the given factor to row srow.
1272 *** Only those elements of s with column index within the
1273 *** given range are added to factor.
1274 *** When possible, range mtx_ALL_COLS/ROWS is faster for sparse rows.
1275 ! ! Calling this without a prior call to mtx_add_row_series_init()
1276 ! ! is an error.<br><br>
1277 ***
1278 ! ! Warning: You MUST release any grabbed row/col created on a matrix
1279 ! ! before destroying that matrix. Failure to do so is fatal.<br><br><br><br>
1280 ***
1281 -$- Does nothing on a bad matrix.
1282 **/
1283 extern void mtx_add_col_series(int32 scol, real64 factor,
1284 mtx_range_t *rowrng);
1285 /**<
1286 *** Adds the given factor to column scol.
1287 *** Only those elements of s with row index within the
1288 *** given range are added to factor.
1289 *** When possible, range mtx_ALL_COLS/ROWS is faster for sparse rows.
1290 ! ! Calling this without a prior call to mtx_add_col_series_init()
1291 ! ! is an error.<br><br>
1292 ***
1293 ! ! Warning: You MUST release any grabbed row/col created on a matrix
1294 ! ! before destroying that matrix. Failure to do so is fatal.<br><br><br><br>
1295 ***
1296 -$- Does nothing on a bad matrix.
1297 **/
1298 extern void mtx_add_row_series_init(mtx_matrix_t mtx, int32 trow,
1299 boolean userow);
1300 /**<
1301 *** Grab or release elements depending on the value of trow.<br><br>
1302 ***
1303 *** If t>=0, grab a row trow of the matrix to have several rows
1304 *** from the same matrix added to it. userow is ignored for t>=0.
1305 *** Only one row at a time may be grabbed for all existing
1306 *** matrices. (One row and one col may be grabbed contemporaneously.)
1307 *** You must release the row (see below) before you can grab another.<br><br>
1308 ***
1309 *** If t is mtx_NONE, release the last row which was grabbed for multiple adds.
1310 *** If userow is TRUE, the current contents of row trow
1311 *** (from the previous call) will be used to release the row.
1312 *** If userow is FALSE, a pessimistic release method will be
1313 *** used instead of the row previously specified.<br><br>
1314 ! ! If ANY destructive operations have been done on the row, call
1315 ! ! this with userow==FALSE.
1316 ! ! The mtx given to a release call must match that given in the grabbing
1317 ! ! or the release is ignored.
1318 *** For very dense rows, it may be faster to call with userow
1319 *** == FALSE since the release with TRUE requires a row traversal.<br><br>
1320 ***
1321 ! ! Warning: You MUST release any grabbed row created on a matrix
1322 ! ! before destroying that matrix. Failure to do so is fatal.<br><br>
1323 ***
1324 -$- Does nothing on a bad matrix.
1325 **/
1326 extern void mtx_add_col_series_init(mtx_matrix_t mtx, int32 tcol,
1327 boolean usecol);
1328 /**<
1329 *** Grab or release elements depending on the value of tcol.<br><br>
1330 ***
1331 *** If t>=0, grab a column tcol of the matrix to have several columns
1332 *** from the same matrix added to it. usecol is ignored for t>=0.
1333 *** Only one column at a time may be grabbed for all existing
1334 *** matrices. (One row and one col may be grabbed contemporaneously.)
1335 *** You must release the column (see below) before you can grab another.<br><br>
1336 ***
1337 *** If t is mtx_NONE, release the last column which was grabbed for multiple adds.
1338 *** If usecol is TRUE, the current contents of column tcol
1339 *** (from the previous call) will be used to release the column.
1340 *** If usecol is FALSE, a pessimistic release method will be
1341 *** used instead of the column previously specified.<br><br>
1342 ! ! If ANY destructive operations have been done on the column, call
1343 ! ! this with usecol==FALSE.
1344 ! ! The mtx given to a release call must match that given in the grabbing
1345 ! ! or the release is ignored.
1346 *** For very dense columns, it may be faster to call with usecol
1347 *** == FALSE since the release with TRUE requires a column traversal.<br><br>
1348 ***
1349 ! ! Warning: You MUST release any grabbed column created on a matrix
1350 ! ! before destroying that matrix. Failure to do so is fatal.<br><br>
1351 ***
1352 -$- Does nothing on a bad matrix.
1353 **/
1354 /* OLD GROUP COMMENT */
1355 /*
1356 -$- mtx_add_row_series(srow,factor,colrng)
1357 -$- mtx_add_col_series(scol,factor,rowrng)
1358 -$- mtx_add_row_series_init(matrix,trow,userow)
1359 -$- mtx_add_col_series_init(matrix,tcol,usecol)
1360 *** mtx_matrix_t matrix;
1361 *** int32 srow,trow,scol,tcol;
1362 *** real64 factor;
1363 *** mtx_range_t *colrng,*rowrng;
1364 *** boolean userow,usecol;
1365 ***
1366 *** mtx_add_row/col_series_init(mtx, t>=0, bool):
1367 *** Grab a row/column t of the matrix to have several rows/columns
1368 *** from the same matrix added to it. bool is ignored for t>=0.
1369 *** Only one row/col at a time may be grabbed for all existing
1370 *** matrices. (One row and one col may be grabbed contemporaneously.)
1371 *** You must release the row/col (see below) before you can grab another.
1372 ***
1373 *** mtx_add_row/col_series_init(mtx, mtx_NONE, userow/col):
1374 *** Release the last row/column which was grabbed for multiple adds.
1375 *** If userow/col is TRUE, the current contents of row/col t
1376 *** (from the previous call) will be used to release the row/col.
1377 *** If userow/col is FALSE, a pessimistic release method will be
1378 *** used instead of the row/col previously specified.
1379 ! ! If ANY destructive operations have been done on the row/col, call
1380 ! ! this with userow/col==FALSE.
1381 ! ! The mtx given to a release call must match that given in the grabbing
1382 ! ! or the release is ignored.
1383 *** For very dense rows/cols, it may be faster to call with userow/col
1384 *** == FALSE since the release with TRUE requires a row/col traversal.
1385 ***
1386 *** mtx_add_row/col_series(s,factor,rowrng)
1387 *** Adds the given multiple of row/column s to trow/tcol.
1388 *** Only those elements of s with column/row index within the
1389 *** given range are added to trow/tcol.
1390 *** When possible, range mtx_ALL_COLS/ROWS is faster for sparse rows.
1391 ! ! Calling these without a prior call to series_init is an error.
1392 ***
1393 ! ! Warning: You MUST release any grabbed row/col created on a matrix
1394 ! ! before destroying that matrix. Failure to do so is fatal.
1395 ***
1396 -$- Does nothing on a bad matrix.
1397 **/
1398
1399 /*
1400 extern wish ! ! ! NOT YET IMPLEMENTED. NO USE FOR THEM SO FAR.
1401 extern void ! ! ! mtx_add_row_org_vec(mtx_matrix_t,int32,
1402 real64 *,real64,
1403 mtx_range_t *, boolean);
1404 extern void ! ! ! mtx_add_col_org_vec(mtx_matrix_t,int32,
1405 real64 *,real64,
1406 mtx_range_t *, boolean);
1407 extern void ! ! ! mtx_add_row_cur_vec(mtx_matrix_t,int32,
1408 real64 *,real64,
1409 mtx_range_t *, boolean);
1410 extern void ! ! ! mtx_add_col_cur_vec(mtx_matrix_t,int32,
1411 real64 *,real64,
1412 mtx_range_t *, boolean);
1413 -$- mtx_add_row_org_vec(matrix,trow,svec,factor,colrng,transpose)
1414 -$- mtx_add_col_org_vec(matrix,tcol,svec,factor,rowrng,transpose)
1415 -$- mtx_add_row_cur_vec(matrix,trow,svec,factor,colrng,transpose)
1416 -$- mtx_add_col_cur_vec(matrix,tcol,svec,factor,rowrng,transpose)
1417 *** mtx_matrix_t matrix;
1418 *** int32 trow,tcol;
1419 *** real64 *svec;
1420 *** real64 factor;
1421 *** mtx_range_t *colrng,*rowrng;
1422 *** boolean transpose;
1423 ***
1424 *** mtx_add_row_org/cur_vec:
1425 *** In matrix trow[col] += factor*svec[col] for elements of svec in colrng.
1426 *** svec is org/cur indexed, by row if !transpose and by column if transpose.
1427 ***
1428 *** mtx_add_col_org/cur_vec:
1429 *** Reverse row <-->col in above
1430 ***
1431 *** This is an absurdly expensive thing to do. Think very carefully about
1432 *** whether you are ignoring existing sparsity info before asking that this
1433 *** mtx primitive be coded.
1434 -$- Does nothing on a bad matrix.
1435 **/
1436
1437 extern void mtx_old_add_row_sparse(mtx_matrix_t mtx, int32 row,
1438 real64 *drow, real64 factor,
1439 mtx_range_t *colrng, int32 *collist);
1440 /**<
1441 *** Adds factor*(drow)[j] to row.
1442 *** Drow is assumed to be the size of the matrix and in current
1443 *** row order, not original order.<br><br>
1444 ***
1445 *** If colrng is mtx_ALL_COLS, then the following is TRUE:
1446 *** If collist is NOT NULL, it will be used instead of colrng
1447 *** to determine which columns j of drow are added to row.
1448 *** Collist must be an array terminated by -1. The sanity of
1449 *** current indices in collist is the users responsibility.
1450 *** In particular, in list mode the value of drow is added blindly
1451 *** rather than being checked for 0.0 and the range of indices is not
1452 *** checked against the matrix size.
1453 *** If collist IS NULL the range will be mtx_ALL_COLS.
1454 *** If a range is specified, collist is ignored and only those
1455 *** elements with column index j within the given range are affected.<br><br>
1456 ***
1457 *** List mode is faster if you are adding the same dense vector
1458 *** (differing only by factor) across many (>2) rows/columns.
1459 *** Range mode is more convenient. The caller should switch between the
1460 *** two as appropriate.<br><br>
1461 -$- Does nothing on a bad matrix.
1462 ***
1463 *** @todo The interface of this operator needs some work!
1464 *** In particular, it should be redone with consideration given
1465 *** to the mtx_sparse_t recently added.
1466 **/
1467 extern void mtx_old_add_col_sparse(mtx_matrix_t mtx, int32 col,
1468 real64 *dcol, real64 factor,
1469 mtx_range_t *rowrng, int32 *rowlist);
1470 /**<
1471 *** Adds factor*(dcol)[j] to col.
1472 *** Dcol is assumed to be the size of the matrix and in current
1473 *** column order, not original order.<br><br>
1474 ***
1475 *** If rowrng is mtx_ALL_ROWS, then the following is TRUE:
1476 *** If rowlist is NOT NULL, it will be used instead of rowrng
1477 *** to determine which rows j of dcol are added to col.
1478 *** Rowlist must be an array terminated by -1. The sanity of
1479 *** current indices in rowlist is the users responsibility.
1480 *** In particular, in list mode the value of dcol is added blindly
1481 *** rather than being checked for 0.0 and the range of indices is not
1482 *** checked against the matrix size.
1483 *** If rowlist IS NULL the range will be mtx_ALL_ROWS.
1484 *** If a range is specified, rowlist is ignored and only those
1485 *** elements with row index j within the given range are affected.<br><br>
1486 ***
1487 *** List mode is faster if you are adding the same dense vector
1488 *** (differing only by factor) across many (>2) rows/columns.
1489 *** Range mode is more convenient. The caller should switch between the
1490 *** two as appropriate.<br><br>
1491 -$- Does nothing on a bad matrix.
1492 ***
1493 *** @todo The interface of this operator needs some work!
1494 *** In particular, it should be redone with consideration given
1495 *** to the mtx_sparse_t recently added.
1496 **/
1497 /* OLD GROUP COMMENT */
1498 /*
1499 *** Note: the interface of this operator needs some work!
1500 *** In particular, it should be redone with consideration given
1501 *** to the mtx_sparse_t recently added.
1502 ***
1503 -$- mtx_old_add_row_sparse(matrix,row,drow,factor,colrng,collist)
1504 -$- mtx_old_add_col_sparse(matrix,col,dcol,factor,rowrng,rowlist)
1505 *** mtx_matrix_t matrix;
1506 *** int32 row,col,*collist,*rowlist;
1507 *** real64 *drow, *dcol;
1508 *** real64 factor;
1509 *** mtx_range_t *colrng,*rowrng;
1510 ***
1511 *** Dense in these function names refers to the row/col data type,
1512 *** a vector as opposed to an mtx row/col, not the information density.
1513 *** Adds factor*(drow/dcol)[j] to row/col.
1514 *** Drow/dcol are assumed to be the size of the matrix and in current
1515 *** row/col order, not original order.
1516 ***
1517 *** If colrng/rowrng is mtx_ALL_COLS/ROWS, then the following is TRUE:
1518 *** If collist/rowlist is NOT NULL, it will be used instead of the rng
1519 *** to determine which columns/rows j of drow/dcol are added to row/col.
1520 *** Collist/rowlist must be an array terminated by -1. The sanity of
1521 *** current indices in collist/rowlist is the users responsibility.
1522 *** In particular, in list mode the value of drow/dcol is added blindly
1523 *** rather than being checked for 0.0 and the range of indices is not
1524 *** checked against the matrix size.
1525 *** If collist/rowlist IS NULL the range will be mtx_ALL_COLS/ROWS.
1526 *** If a range is specified, collist/rowlist is ignored and only those
1527 *** elements with column/row index j within the given range are affected.
1528 ***
1529 *** List mode is faster if you are adding the same dense vector
1530 *** (differing only by factor) across many (>2) rows/columns.
1531 *** Range mode is more convenient. The caller should switch between the
1532 *** two as appropriate.
1533 -$- Does nothing on a bad matrix.
1534 **/
1535
1536 extern void mtx_add_row_sparse(mtx_matrix_t mtx, int32 row,
1537 real64 factor, mtx_sparse_t *sparse);
1538 /**< @todo mtx_add_row_sparse() NOT IMPLEMENTED. */
1539 extern void mtx_add_col_sparse(mtx_matrix_t mtx, int32 col,
1540 real64 factor, mtx_sparse_t *sparse);
1541 /**< @todo mtx_add_col_sparse() NOT IMPLEMENTED. */
1542 /* OLD GROUP COMMENT */
1543 /*
1544 -$- mtx_add_row_sparse(matrix,row,factor,sparse)
1545 -$- mtx_add_col_sparse(matrix,col,factor,sparse)
1546 *** mtx_matrix_t matrix;
1547 *** int32 row,col;
1548 *** real64 factor;
1549 *** mtx_sparse_t *sparse; expected to be in org coords.
1550 *** NOT IMPLEMENTED.
1551 **/
1552
1553 extern size_t mtx_size(mtx_matrix_t mtx);
1554 /**<
1555 *** Returns the amount of memory in use by a matrix and all its
1556 *** bits and pieces.
1557 *** Slaves report only their incremental cost, that is they do
1558 *** not report the cost of the structures they share with a master.
1559 *** Masters do report the cost of their slaves.
1560 **/
1561 extern size_t mtx_chattel_size(mtx_matrix_t mtx);
1562 /**<
1563 *** Returns the memory used by all slaves of the matrix given
1564 *** that is not shared with the master. Returns 0 from a slave.
1565 **/
1566 /* OLD GROUP COMMENT */
1567 /*
1568 *** size=mtx_size(mtx)
1569 *** size=mtx_chattel_size(mtx)
1570 *** size_t size;
1571 *** mtx_matrix_t mtx;
1572 ***
1573 *** mtx_size(mtx);
1574 *** Returns the amount of memory in use by a matrix and all its
1575 *** bits and pieces.
1576 *** Slaves report only their incremental cost, that is they do
1577 *** not report the cost of the structures they share with a master.
1578 *** Masters do report the cost of their slaves.
1579 ***
1580 *** mtx_chattel_size(master);
1581 *** Returns the memory used by all slaves of the matrix given
1582 *** that is not shared with the master. Returns 0 from a slave.
1583 **/
1584
1585 extern void mtx_free_reused_mem(void);
1586 /**<
1587 *** <!-- mtx_free_reused_mem() -->
1588 ***
1589 *** Deallocates any memory that mtx may be squirrelling away for
1590 *** internal reuse. Calling this while any slv_system_t exists
1591 *** is likely to be fatal: handle with care.
1592 **/
1593
1594 /* ********************************************************************* *\
1595 mtx io routines
1596 \* ********************************************************************* */
1597 extern void mtx_write_sparse(FILE *file, mtx_sparse_t *sparse);
1598 /**<
1599 *** <!-- mtx_write_sparse(file,sparse); -->
1600 *** Outputs sizes and data of sparse vector to the file given.
1601 **/
1602
1603 extern void mtx_write_region_human_f(FILE *file,
1604 mtx_matrix_t mtx,
1605 mtx_region_t *region,
1606 int colwise,
1607 int orgwise);
1608 /**<
1609 *** Internal function to output a matrix region to file.
1610 *** Implementation function for
1611 *** - mtx_write_region_human()
1612 *** - mtx_write_region_human_rows()
1613 *** - mtx_write_region_human_cols()
1614 *** - mtx_write_region_human_orgrows()
1615 *** - mtx_write_region_human_orgcols()
1616 ***
1617 *** Outputs permutation and values of the nonzero elements in the
1618 *** given region of the mtx to the file given.
1619 *** If colwise != 0, output will be column grouped,
1620 *** otherwise it will be row grouped.
1621 *** If orgwise != 0, only org indices will be printed.
1622 *** Doesn't care about master/slave status.
1623 **/
1624 /* OLD GROUP COMMENT */
1625 /*
1626 *** MACROS:
1627 *** mtx_write_region_human(file,mtx,region);
1628 *** Grandfather support for the old usages.
1629 *** mtx_write_region_human_rows(file,mtx,region);
1630 *** Writes row oriented human readable output of a mtx region.
1631 *** mtx_write_region_human_cols(file,mtx,region);
1632 *** Writes column oriented human readable output of a mtx region.
1633 ***
1634 *** Internal:
1635 *** mtx_write_region_human_f(file,mtx,region,colwise,orgwise);
1636 *** Outputs permutation and values of the nonzero elements in the
1637 *** given region of the mtx to the file given.
1638 *** If colwise != 0, output will be column grouped,
1639 *** otherwise it will be row grouped.
1640 *** If orgwise != 0, only org indices will be printed.
1641 *** Doesn't care about master/slave status.
1642 ***
1643 mmm macro extern void mtx_write_region_human(file,mtx,region)
1644 mmm macro extern void mtx_write_region_human_rows(file,mtx,region)
1645 mmm macro extern void mtx_write_region_human_cols(file,mtx,region)
1646 mmm macro extern void mtx_write_region_human_orgrows(file,mtx,region)
1647 mmm macro extern void mtx_write_region_human_orgcols(file,mtx,region)
1648 **/
1649 #define mtx_write_region_human(f,m,r) mtx_write_region_human_f((f),(m),(r),0,0)
1650 /**<
1651 * Grandfather support for the old usages.
1652 * @see mtx_write_region_human_f().
1653 */
1654 #define mtx_write_region_human_rows(f,m,r) \
1655 mtx_write_region_human_f((f),(m),(r),0,0)
1656 /**<
1657 * Writes row oriented human readable output of a mtx region.
1658 * @see mtx_write_region_human_f().
1659 */
1660 #define mtx_write_region_human_cols(f,m,r) \
1661 mtx_write_region_human_f((f),(m),(r),1,0)
1662 /**<
1663 * Writes column oriented human readable output of a mtx region.
1664 * @see mtx_write_region_human_f().
1665 */
1666 #define mtx_write_region_human_orgrows(f,m,r) \
1667 mtx_write_region_human_f((f),(m),(r),0,1)
1668 /**<
1669 * Writes row oriented human readable output of a mtx region.
1670 * @see mtx_write_region_human_f().
1671 */
1672 #define mtx_write_region_human_orgcols(f,m,r) \
1673 mtx_write_region_human_f((f),(m),(r),1,1)
1674 /**<
1675 * Writes column oriented human readable output of a mtx region.
1676 * @see mtx_write_region_human_f().
1677 */
1678
1679 ASC_DLLSPEC(void ) mtx_write_region(FILE *file,
1680 mtx_matrix_t mtx,
1681 mtx_region_t *region);
1682 /**<
1683 *** <!-- mtx_write_region(file,mtx,region) -->
1684 *** Outputs permutation and values of the nonzero elements in the
1685 *** given region of the mtx to the file given along with the matrix
1686 *** size.
1687 *** The coordinates of the nonzeros written will be in original
1688 *** (unpermuted) indexing. This file is for mtx_read_region, but is
1689 *** in ASCII for portability.
1690 *** Doesn't care about master/slave status.<br><br>
1691 *** Not intended for human consumptions, but just so you know
1692 *** permutations are written in order r2org org2r c2org org2c.
1693 *** parity is not written.<br><br>
1694 *** If the region given is mtx_ENTIRE_MATRIX, and there is a
1695 *** block structure present in the matrix, it will be written as well
1696 *** and the symbolic rank will go out with the block structure.
1697 **/
1698
1699 extern mtx_matrix_t mtx_read_region(FILE *file,
1700 mtx_matrix_t mtx,
1701 int transposed);
1702 /**<
1703 *** <!-- mtx_read_region(file,mtx,transposed) -->
1704 *** Reads a matrix region.
1705 *** From the file pointer, does the following:
1706 *** - Gets the matrix order of the data in the file.
1707 *** - If mtx is NULL, creates it.
1708 *** - Expands the matrix given or created to the data order if it is too small.
1709 *** - Permutes the matrix to the permutation found in the file.
1710 *** - Reads the region limits in the file and clears that region in the mtx.
1711 *** - Reads coefficients from the file.
1712 ***
1713 *** transposed governs if the matrix data should be treated as
1714 *** row col or col row
1715 ! ! Warnings: Do not add incidence data to the
1716 ! ! file except in those org_rows and org_cols which are within the
1717 ! ! region specified (note that the region is given in CUR coordinates.)
1718 ! ! Adding incidence outside the region may lead to loss of internal
1719 ! ! consistency unless the entire mtx given is empty when this is called.
1720 ! ! If you send a matrix larger than the order of data in the file,
1721 ! ! you should do a reset to it first to undo the previous permutation.<br><br>
1722 ***
1723 *** Return value is the pointer to the mtx given or created.
1724 *** If error in reading matrix file, mtx returned may be incomplete or NULL
1725 *** if the mtx given was NULL.
1726 *** If the file read has block information in it and further the user sent
1727 *** in NULL to this function, block info will be read and added to the
1728 *** returned matrix.<br><br>
1729 ***
1730 *** Doesn't care about master/slave status.
1731 **/
1732
1733 extern void mtx_write_region_matlab(FILE *file,
1734 mtx_matrix_t mtx,
1735 mtx_region_t *region);
1736 /**<
1737 *** <!-- mtx_write_region_matlab(file,mtx,region) -->
1738 *** Outputs values of the nonzero elements in the
1739 *** given region of the mtx to the file in matlab/harwell sparse format.
1740 *** The "a=[\n" and trailing "];\n" are not supplied, since the caller
1741 *** knows better what they should look like.
1742 *** Row/column coordinates printed are the cur coordinates.
1743 **/
1744
1745 ASC_DLLSPEC(void ) mtx_write_region_plot(FILE *file,
1746 mtx_matrix_t mtx,
1747 mtx_region_t *region);
1748 /**<
1749 *** <!-- mtx_write_region_plot(file,mtx,region) -->
1750 *** Outputs the coordinates of elements to file with format suitable
1751 *** for xgraph consumption from the given region of the mtx.
1752 *** A suitable xgraph invocation would be "xgraph -nl -m filename".
1753 *** Doesn't care about master/slave status.
1754 **/
1755
1756 ASC_DLLSPEC(void ) mtx_write_region_csr(FILE *file,
1757 mtx_matrix_t mtx,
1758 mtx_region_t *region,
1759 int offset);
1760 /**<
1761 *** Writes the given region of the matrix to the named file.
1762 *** Will write the entire matrix if the region is mtx_ENTIRE_MATRIX.
1763 *** This function writes out the matrix in compressed row format.
1764 *** mtx_write_region_smms() writes out the matrix in a form digestible by
1765 *** Alvarado's Sparse Matrix Manipulation System.
1766 *** There may be a _ccs version (column based) one day.
1767 *** offset controls whether fortran (1) or c style indexing is done.
1768 *** Doesn't care about master/slave status.
1769 **/
1770 ASC_DLLSPEC(void ) mtx_write_region_smms(FILE *file,
1771 mtx_matrix_t mtx,
1772 mtx_region_t *region,
1773 int offset);
1774 /**<
1775 *** Writes the given region of the matrix to the named file.
1776 *** Will write the entire matrix if the region is mtx_ENTIRE_MATRIX.
1777 *** The _smms version writes out the matrix in a form digestible by
1778 *** Alvarado's Sparse Matrix Manipulation System.
1779 *** mtx_write_region_csr() writes out the matrix in compressed row format.
1780 *** There may be a _ccs version (column based) one day.
1781 *** offset controls whether fortran (1) or c style indexing is done.
1782 *** Doesn't care about master/slave status.
1783 **/
1784 extern mtx_matrix_t mtx_read_smms(FILE *file,
1785 mtx_matrix_t mtx,
1786 int transpose);
1787
1788 /**<
1789 *** Reads a matrix in smms format. If a NULL matrix
1790 *** is sent in, it will create and return it. If a non NULL matrix
1791 *** is given, the order will be increased if necessary. The contents
1792 *** of the old mtx, will be blown away. The transpose flag dictates
1793 *** whether the transpose should be read in.
1794 *** Doesn't care about master/slave status.
1795 **/
1796 /* OLD GROUP COMMENT */
1797 /*
1798 *** mtx_write_region_csr(file,mtx,region,offset)
1799 *** mtx_write_region_smms(file,mtx,region,offset)
1800 *** mtx = mtx_read_smms(file,mtx,transpose);
1801 ***
1802 *** Writes the given region of the matrix to the named file.
1803 *** Will write the entire matrix if the region is mtx_ENTIRE_MATRIX.
1804 *** The _csr version writes out the matrix in compressed row format.
1805 *** The _smms version writes out the matrix in a form digestible by
1806 *** Alvarado's Sparse Matrix Manipulation System.
1807 *** There may be a _ccs version (column based) one day.
1808 *** offset controls whether fortran (1) or c style indexing is done.
1809 ***
1810 *** mtx_read_smms reads a matrix in smms format. If a NULL matrix
1811 *** is sent in, it will create and return it. If a non NULL matrix
1812 *** is given, the order will be increased if necessary. The contents
1813 *** of the old mtx, will be blown away. The transpose flag dictates
1814 *** whether the transpose should be read in.
1815 *** Doesn't care about master/slave status.
1816 **/
1817
1818 extern void mtx_exception_recover(void);
1819 /**<
1820 *** <!-- mtx_exception_recover(); -->
1821 *** Cleans up after a floating point exception has
1822 *** occurred during matrix manipulations. You don't need to know
1823 *** what this does, except that you should call it any time this may
1824 *** have occurred. Several functions use
1825 *** data structures that can cause insanity in the event of exception.<br><br>
1826 ***
1827 *** Just for the curious, it resets several internal data structures
1828 *** needed including ones used in the operators:
1829 *** - mtx_add_row/col()
1830 *** - mtx_add_row/col_series()
1831 *** - mtx_add_row/col_series_init()
1832 *** - mtx_assemble()
1833 *** - mtx_add_outer_product()
1834 **/
1835
1836 extern void mtx__debug_output(FILE *file, mtx_matrix_t mtx);
1837 /**<
1838 *** <!-- mtx_debug_output(fp,matrix) -->
1839 *** <!-- FILE *fp; -->
1840 *** <!-- mtx_matrix_t matrix; -->
1841 ***
1842 *** Debug outputs all internal information about a matrix to file.
1843 *** In the process, integrity checks are performed.
1844 *** If file is NULL, output goes to default (which is stderr.)
1845 *** Doesn't care about master/slave status.
1846 **/
1847
1848 #endif /**< __MTX_BASIC_H_SEEN__ */

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