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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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