Parent Directory | 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)

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 |