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

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