Parent Directory | Revision Log

Revision **1319** -
(**show annotations**)
(**download**)
(**as text**)

*Tue Mar 6 00:22:28 2007 UTC*
(13 years, 4 months ago)
by *jpye*

File MIME type: text/x-chdr

File size: 61872 byte(s)

File MIME type: text/x-chdr

File size: 61872 byte(s)

Added test suite for linsolqr (very early days still) for checking by Ben

1 | /* ASCEND Solver Interface |

2 | Copyright (C) 1990 Karl Michael Westerberg |

3 | Copyright (C) 1993 Joseph Zaher |

4 | Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan |

5 | Copyright (C) 1995 Benjamin Andrew Allan, Kirk Andre' Abbott |

6 | Copyright (C) 1996 Benjamin Andrew Allan |

7 | Copyright (C) 2006 Carnegie Mellon University |

8 | |

9 | This program is free software; you can redistribute it and/or |

10 | modify it under the terms of the GNU General Public License |

11 | as published by the Free Software Foundation; either version 2 |

12 | of the License, or (at your option) any later version. |

13 | |

14 | This program is distributed in the hope that it will be useful, |

15 | but WITHOUT ANY WARRANTY; without even the implied warranty of |

16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |

17 | GNU General Public License for more details. |

18 | |

19 | You should have received a copy of the GNU General Public License |

20 | along with this program; if not, write to the Free Software |

21 | Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |

22 | *//** @file |

23 | mtx2: Ascend Sparse Matrix Package. |

24 | |

25 | Requires |

26 | #include "utilities/ascConfig.h" |

27 | #include "mtx.h" |

28 | *//* |

29 | Originally 'mtx' by Karl Michael Westerberg, 5/3/90 |

30 | New version 'mtx2' by Benjamin Andrew Allan |

31 | Last in CVS: $Revision: 1.13 $ $Date: 2000/01/25 02:27:10 $ $Author: ballan $ |

32 | */ |

33 | |

34 | #ifndef ASC_MTX_BASIC_H_ |

35 | #define ASC_MTX_BASIC_H |

36 | |

37 | /** @addtogroup linear Linear |

38 | @{ |

39 | */ |

40 | |

41 | /***********************************************************************\ |

42 | mtx types creation/destruction/info routines |

43 | \***********************************************************************/ |

44 | extern boolean check_matrix(mtx_matrix_t mtx, char *file, int line); |

45 | /**< |

46 | * Implementation function for mtx_check_matrix(). |

47 | * Do not call this function directly - use mtx_check_matrix() instead. |

48 | * @todo check_matrix() should return TRUE/FALSE, not 1/0. |

49 | */ |

50 | #define mtx_check_matrix(mtx) check_matrix((mtx),__FILE__,__LINE__) |

51 | /**< |

52 | ** Checks the integrity flag of the matrix. |

53 | ** Returns 1 if mtx is ok (non-NULL, integrity flag ok). |

54 | ** Otherwise returns 0. If mtx is not ok, a message is |

55 | ** printed to g_mtxerr. If mtx is a slave, the integrity |

56 | ** on the master mtx is also checked. |

57 | ** @param mtx mtx_matrix_t, the matrix to check. |

58 | ** @return 1 if given matrix is valid, 0 otherwise. |

59 | **/ |

60 | |

61 | extern boolean check_sparse(const mtx_sparse_t * const sp, |

62 | char *file, int line); |

63 | /**< |

64 | * Implementation function for mtx_check_sparse(). |

65 | * Do not call this function directly - use mtx_check_sparse() instead. |

66 | * @todo check_sparse() should return TRUE/FALSE, not 1/0. |

67 | */ |

68 | #define mtx_check_sparse(sp) check_sparse((sp),__FILE__,__LINE__) |

69 | /**< |

70 | ** Checks the consistency of a sparse matrix as best it can. |

71 | ** Returns 1 if sp is ok, FALSE if something wierd is found. |

72 | ** If sp is not ok, a message is printed to g_mtxerr. |

73 | ** @param sp const mtx_sparse_t * const, the sparse matrix to check. |

74 | ** @return 1 if given matrix is valid, 0 otherwise. |

75 | **/ |

76 | |

77 | ASC_DLLSPEC mtx_coord_t *mtx_coord(mtx_coord_t *coordp, int32 row, int32 col); |

78 | /**< |

79 | Places the values of row and col into coordp and returns |

80 | the coordp pointer again. |

81 | |

82 | Typical usage: <pre> |

83 | { |

84 | mtx_coord_t coord; |

85 | value = mtx_value(matrix,mtx_coord(&coord,row,col)); |

86 | } </pre> |

87 | */ |

88 | extern mtx_range_t *mtx_range(mtx_range_t *rangep, int32 low, int32 high); |

89 | /**< |

90 | Places the values of low and high into rangep and returns |

91 | the rangep pointer again. |

92 | */ |

93 | ASC_DLLSPEC mtx_region_t *mtx_region(mtx_region_t *regionp, |

94 | int32 rowlow, int32 rowhigh, |

95 | int32 collow, int32 colhigh); |

96 | /**< |

97 | Places the ranges specified by (rowlow,rowhigh) and |

98 | (collow,colhigh) into regionp and returns the |

99 | regionp pointer again. |

100 | */ |

101 | |

102 | ASC_DLLSPEC void mtx_zero_int32(int32 *data, int len); |

103 | /**< Zeros an int32 vector of specified length. Ignores NULL input vectors. */ |

104 | extern void mtx_zero_real64(real64 *data, int len); |

105 | /**< Zeros a real64 vector of specified length. Ignores NULL input vectors. */ |

106 | extern void mtx_zero_ptr(void **data, int len); |

107 | /**< Zeros a vector of pointers of specified length. Ignores NULL input vectors. */ |

108 | #define mtx_zero_char(ar,len) if ((ar)!=NULL) memset((ar),0,(len)) |

109 | /**< |

110 | Zeros a char vector of specified length. Ignores NULL input vectors. |

111 | */ |

112 | |

113 | ASC_DLLSPEC mtx_matrix_t mtx_create(void); |

114 | /**< |

115 | Creates a 0-order matrix and returns a handle to it. |

116 | Matrix created is a master with no slaves. |

117 | */ |

118 | |

119 | extern mtx_matrix_t mtx_create_slave(mtx_matrix_t master); |

120 | /**< |

121 | *** Create and return a matrix which shares all structural |

122 | *** information EXCEPT incidence pattern/values with the |

123 | *** master matrix given. A master may have as many slaves |

124 | *** as desired. Slaves cannot have slaves. Slaves cannot |

125 | *** become masters. Copies of slave matrices are totally |

126 | *** independent of both slave and master.<br><br> |

127 | *** |

128 | *** All structural manipulation/query function calls will |

129 | *** be passed up to the master. When the master is resized, |

130 | *** all its slaves are resized.<br><br> |

131 | *** |

132 | *** This function will return NULL if called on a matrix which |

133 | *** is a slave or otherwise bad.<br><br> |

134 | *** |

135 | *** Slave matrices exist to: |

136 | *** - Let the user keep a whole stack of matrices in permutation |

137 | *** synchrony for the price of structural operations on only |

138 | *** the master matrix. Principally, this reduces mtx_drag cost. |

139 | *** - Reduce the memory overhead of a matrix duplicate |

140 | *** when the duplicate is to be kept in structural synchrony. |

141 | *** The additional memory required to maintain a slave matrix |

142 | *** is the cost of the incidence stored in the slave plus |

143 | *** 2*mtx_capacity(master)*sizeof(double) + sizeof(void *). |

144 | *** - Demonstrate that C can knock the cookies out of FORTRAN |

145 | *** in speed while delivering twice the semantic content |

146 | *** in the output of a matrix factorization routine. |

147 | **/ |

148 | |

149 | extern void mtx_debug_redirect_freeze(void); |

150 | /**< |

151 | *** Stops future mtx_create()/mtx_create_slave() from |

152 | *** redirecting errors back to stderr. |

153 | **/ |

154 | |

155 | ASC_DLLSPEC void mtx_destroy(mtx_matrix_t matrix); |

156 | /**< |

157 | *** Destroys the matrix, freeing the memory it occupied. |

158 | *** Does nothing if matrix fails mtx_check_matrix. |

159 | *** Destroys all slaves associated with the matrix if |

160 | *** it is a master. If mtx is a slave, its master must |

161 | *** also pass check_matrix before slave is destroyed. |

162 | **/ |

163 | |

164 | extern mtx_sparse_t *mtx_create_sparse(int32 capacity); |

165 | /**< |

166 | *** Creates a sparse vector with capacity given and returns it. |

167 | *** The length of the sparse data is initialized to 0. |

168 | *** If insufficient memory is available, returns NULL. |

169 | **/ |

170 | |

171 | ASC_DLLSPEC void mtx_destroy_sparse(mtx_sparse_t *sp); |

172 | /**< |

173 | *** Given a pointer to the sparse structure, deallocates everything to |

174 | *** do with the structure, including the structure itself. The pointer |

175 | *** sp is invalidated. Handles NULL gracefully. |

176 | **/ |

177 | |

178 | extern void mtx_destroy_blocklist(mtx_block_t *bl); |

179 | /**< |

180 | *** Given a pointer to the block structure, deallocates everything to |

181 | *** do with the structure, including the structure itself. The pointer |

182 | *** bl is invalidated. Handles NULL gracefully. |

183 | *** If nblocks is 0 and the region array is not, region pointer will be |

184 | *** abandoned. |

185 | **/ |

186 | |

187 | extern mtx_matrix_t mtx_duplicate_region(mtx_matrix_t matrix, |

188 | mtx_region_t *region, |

189 | real64 drop); |

190 | /**< |

191 | *** Creates a slave of the matrix given (or of the master of the matrix |

192 | *** given). This operator provides a low overhead way of |

193 | *** saving a matrix region for later computation. The slave matrix |

194 | *** returned is kept permuted to the same ordering as the master from |

195 | *** which it was created.<br><br> |

196 | *** |

197 | *** The incidence is copied from the matrix given, even if the matrix |

198 | *** given is the slave of another matrix. During the copy, all Aij such |

199 | *** that abs(Aij) < drop in the matrix given are ignored.<br><br> |

200 | *** |

201 | *** If you want a slave but do not want to copy any incidence, you should |

202 | *** just use mtx_create_slave(matrix); instead.<br><br> |

203 | *** |

204 | -$- Does nothing if matrix fails mtx_check_matrix; returns NULL. |

205 | **/ |

206 | |

207 | extern mtx_matrix_t mtx_copy_options(mtx_matrix_t matrix, |

208 | boolean blocks, boolean incidence, |

209 | mtx_region_t *region, real64 drop); |

210 | /**< |

211 | *** General matrix copy function. |

212 | *** All operations can take either a master or a slave matrix |

213 | *** and all return a NEW master. If you want a slave copy, see |

214 | *** mtx_duplicate_region.<br><br> |

215 | *** |

216 | *** This function should generally be considered an implementation |

217 | *** function not to be called directly. Use one of the macros described |

218 | *** below to perform the type of copy desired. |

219 | *** |

220 | *** <pre> |

221 | *** mtx_copy_complete(mtx) |

222 | *** Copies everything to do with a mtx. Copying the block information |

223 | *** is usually redundant because the caller should use the block info |

224 | *** from the original matrix, but in the odd event that such is not |

225 | *** the case, we provide the copy_complete operator. |

226 | *** Note that if you are copying a matrix created by mtx_copy |

227 | *** or mtx_copy_wo_incidence then the copy returned will not have |

228 | *** block data. |

229 | *** |

230 | *** mtx_copy(mtx) |

231 | *** Copies the matrix except for the block structure and returns |

232 | *** a handle to the new copy. Most commonly used. |

233 | *** |

234 | *** mtx_copy_region(matrix,region) |

235 | *** Copies the matrix excluding the block structure and any |

236 | *** incidence outside the region given. |

237 | *** |

238 | *** mtx_copy_region_drop(matrix,region,drop) |

239 | *** As mtx_copy_region(), except that incidence of magnitude < abs(drop) is |

240 | *** not copied. Note that in C 0.0 !< 0.0. Use a really small number if |

241 | *** you want 0s suppressed in the copy. |

242 | *** |

243 | *** mtx_copy_wo_incidence(mtx) |

244 | *** Copies the matrix except for the nonzero and block structure |

245 | *** and returns a handle to the new copy. If you find yourself |

246 | *** doing mtx_copy followed by mtx_clear, use this instead.<br><br> |

247 | *** |

248 | -$- Does nothing if matrix fails mtx_check_matrix; returns NULL. |

249 | *** </pre> |

250 | **/ |

251 | #define mtx_copy(m) mtx_copy_options((m),FALSE,TRUE,mtx_ENTIRE_MATRIX,0.0) |

252 | /**< See mtx_copy_options(). */ |

253 | #define mtx_copy_region(m,r) mtx_copy_options((m),FALSE,TRUE,(r),0.0) |

254 | /**< See mtx_copy_options(). */ |

255 | #define mtx_copy_region_drop(m,r,d) mtx_copy_options((m),FALSE,TRUE,(r),(d)) |

256 | /**< See mtx_copy_options(). */ |

257 | #define mtx_copy_wo_incidence(m) mtx_copy_options((m),FALSE,FALSE,NULL,0.0) |

258 | /**< See mtx_copy_options(). */ |

259 | #define mtx_copy_complete(m) mtx_copy_options((m),TRUE,TRUE, mtx_ENTIRE_MATRIX,0.0) |

260 | /**< See mtx_copy_options(). */ |

261 | |

262 | ASC_DLLSPEC int32 mtx_order(mtx_matrix_t matrix); |

263 | /**< |

264 | *** Returns the order of the matrix, be it master or slave. |

265 | -$- Order of a corrupt matrix is -1; |

266 | **/ |

267 | |

268 | ASC_DLLSPEC int32 mtx_capacity(mtx_matrix_t matrix); |

269 | /**< |

270 | *** Returns the capacity of the matrix, be it master or slave. |

271 | *** Original row/column numbers must lie in the range 0 <= ndx < cap. |

272 | *** cap may be larger than the matrix order if the order of the matrix |

273 | *** was ever at time higher than it is now. |

274 | -$- capacity of a corrupt matrix is -1; |

275 | **/ |

276 | |

277 | ASC_DLLSPEC void mtx_set_order(mtx_matrix_t matrix, int32 order); |

278 | /**< |

279 | *** Changes the order of the matrix to the new order, either truncating |

280 | *** the matrix, or extending it with blank rows and columns if necessary. |

281 | *** Does not change the incidence pattern if the matrix is being expanded. |

282 | *** Calls on slaves are passed up to the master. Calls on a master reset |

283 | *** the order for all of its slaves. |

284 | *** |

285 | *** @bug This should return a memory allocation status boolean, |

286 | *** but doesn't. Does nothing to a bad matrix. |

287 | **/ |

288 | |

289 | extern void mtx_clear_coord(mtx_matrix_t matrix, int32 row, int32 col); |

290 | /**< |

291 | *** Erase an element in a matrix. The specified element must |

292 | *** exist to be erased. |

293 | -$- Does nothing to a bad matrix if MTX_DEBUG is defined. |

294 | *** Will work as usual on masters/slaves. |

295 | *** @see mtx_clear() for more about matrix clearing functions. |

296 | **/ |

297 | |

298 | extern void mtx_clear_row(mtx_matrix_t matrix, int32 row, mtx_range_t *rng); |

299 | /**< |

300 | *** Erase a range of elements in a single row of a matrix. |

301 | -$- Does nothing to a bad matrix if MTX_DEBUG is defined. |

302 | *** Will work as usual on masters/slaves. |

303 | *** @see mtx_clear() for more about matrix clearing functions. |

304 | **/ |

305 | |

306 | extern void mtx_clear_col(mtx_matrix_t matrix,int32 col, mtx_range_t *rng); |

307 | /**< |

308 | *** Erase a range of elements in a single column of a matrix. |

309 | -$- Does nothing to a bad matrix if MTX_DEBUG is defined. |

310 | *** Will work as usual on masters/slaves. |

311 | *** @see mtx_clear() for more about matrix clearing functions. |

312 | **/ |

313 | |

314 | extern void mtx_clear_rowlist(mtx_matrix_t matrix, |

315 | mtx_sparse_t *sp, mtx_range_t *rng); |

316 | /**< |

317 | *** NOT IMPLEMENTED. |

318 | *** Erase a range of elements in the list of rows given in |

319 | *** the idata of the sparse. The data of the sparse need not |

320 | *** be valid as it will not be referenced. |

321 | -$- Does nothing to a bad matrix if MTX_DEBUG is defined. |

322 | *** Will work as usual on masters/slaves. |

323 | *** @see mtx_clear() for more about matrix clearing functions. |

324 | **/ |

325 | |

326 | extern void mtx_clear_collist(mtx_matrix_t matrix, |

327 | mtx_sparse_t *sp, mtx_range_t *rng); |

328 | /**< |

329 | *** NOT IMPLEMENTED. |

330 | *** Erase a range of elements in the list of columns given in |

331 | *** the idata of the sparse. The data of the sparse need not |

332 | *** be valid as it will not be referenced. |

333 | -$- Does nothing to a bad matrix if MTX_DEBUG is defined. |

334 | *** Will work as usual on masters/slaves. |

335 | *** @see mtx_clear() for more about matrix clearing functions. |

336 | **/ |

337 | |

338 | ASC_DLLSPEC void mtx_clear_region(mtx_matrix_t matrix, mtx_region_t *region); |

339 | /**< |

340 | *** Erases all elements in the given region. |

341 | -$- Does nothing to a bad matrix if MTX_DEBUG is defined.<br><br> |

342 | *** mtx_clear_region(slave,region) can be used without affecting other |

343 | *** slaves or the master. |

344 | *** mtx_clear_region(master,region) affects only the master UNLESS |

345 | *** region is mtx_ENTIRE_MATRIX. mtx_ENTIRE_MATRIX clears the master |

346 | *** and ALL incidence in ALL its slaves. |

347 | *** @see mtx_clear() for more about matrix clearing functions. |

348 | **/ |

349 | |

350 | extern void mtx_reset_perm(mtx_matrix_t matrix); |

351 | /**< |

352 | *** Restores the original row/column ordering. |

353 | -$- Does nothing to a bad matrix if MTX_DEBUG is defined.<br><br> |

354 | *** Note that mtx_reset_perm() invalidates any data saved with |

355 | *** the mtx_*_block_perm functions.<br><br> |

356 | *** mtx_reset_perm(master or slave) passes the reset up to the master. |

357 | *** @see mtx_clear() for more about matrix clearing functions. |

358 | **/ |

359 | |

360 | ASC_DLLSPEC void mtx_clear(mtx_matrix_t matrix); |

361 | /**< |

362 | *** Clears everything in the matrix. |

363 | -$- Does nothing to a bad matrix if MTX_DEBUG is defined.<br><br> |

364 | *** |

365 | *** It is generally most efficient to clear as many incidences in possible |

366 | *** in a single call. When a set of adjacent rows/columns is to be cleared, |

367 | *** use mtx_clear_region. If a rather disjoint set is to be cleared (such |

368 | *** as the nonlinear rows of a mixed linear/nonlinear jacobian) use |

369 | *** mtx_clear_rowlist/collist.<br><br> |

370 | *** |

371 | *** Note that mtx_clear() invalidates any data saved with the |

372 | *** mtx_*_block_perm functions.<br><br> |

373 | *** mtx_clear(master or slave) passes up to the master. |

374 | **/ |

375 | |

376 | |

377 | ASC_DLLSPEC real64 mtx_value(mtx_matrix_t matrix, mtx_coord_t *coord); |

378 | /**< |

379 | *** |

380 | *** Use of mtx_value() should be avoided if at all possible |

381 | *** inside loops. See mtx_next_in_* for doing mtx/vector operations. |

382 | *** Returns the value of the given element in the matrix. |

383 | *** Doesn't matter whether a matrix is slave or master. |

384 | -$- Returns 0.0/does nothing from/to a bad matrix. |

385 | **/ |

386 | |

387 | ASC_DLLSPEC void mtx_set_value(mtx_matrix_t matrix, |

388 | mtx_coord_t *coord, real64 value); |

389 | /**< |

390 | *** Sets the value of the given element in the matrix. |

391 | *** Because the only sane usage of mtx_set_value() is for |

392 | *** things like setting something in the diagonal, |

393 | *** mtx_set_value() remembers the last place mtx_value() returned |

394 | *** and checks it before starting a search. Any element destruction |

395 | *** causes mtx_set_value() to forget, however. |

396 | *** This remembrance is matrix specific and is not affected by |

397 | *** element destruction in other unrelated matrices. |

398 | *** Like mtx_value(), use of mtx_set_value() should be avoided if at |

399 | *** all possible inside loops. See mtx_next_in_* for doing mtx/vector |

400 | *** operations.<br><br> |

401 | *** |

402 | *** mtx_set_value(mtx,coord,0.0) will create no incidence if none |

403 | *** is presently there, nor does it delete an incidence. |

404 | *** |

405 | *** Doesn't matter whether a matrix is slave or master. |

406 | *** |

407 | -$- Returns 0.0/does nothing from/to a bad matrix. |

408 | *** @see mtx_fill_value() |

409 | **/ |

410 | |

411 | ASC_DLLSPEC void mtx_fill_value(mtx_matrix_t matrix, |

412 | mtx_coord_t *coord, real64 value); |

413 | /**< |

414 | *** Sets the value of the given element in the matrix. |

415 | *** Use this function in place of mtx_set_value() in those instances |

416 | *** where the caller knows there currently exists no element at the |

417 | *** coordinate whose value is to be set. mtx_fill_value() can also be |

418 | *** used if a mtx_assemble() call will happen before ANY other numeric |

419 | *** or structural calls are made. |

420 | *** |

421 | *** Doesn't matter whether a matrix is slave or master. |

422 | *** |

423 | -$- Returns 0.0/does nothing from/to a bad matrix. |

424 | *** @see mtx_fill_org_value() |

425 | **/ |

426 | |

427 | extern void mtx_fill_org_value(mtx_matrix_t matrix, |

428 | const mtx_coord_t *coord, |

429 | real64 value); |

430 | /**< |

431 | *** Sets the value of the given element in the matrix. |

432 | *** This function is just like mtx_fill_value() except the location |

433 | *** given is understood as the (orgrow,orgcol) location to put the fill. |

434 | *** |

435 | *** Doesn't matter whether a matrix is slave or master. |

436 | *** |

437 | -$- Returns 0.0/does nothing from/to a bad matrix. |

438 | **/ |

439 | |

440 | /** grandfathering old linsol. @todo Remove when linsolqr replaces linsol. */ |

441 | #define mtx_add_value(a,b,c) mtx_fill_value((a),(b),(c)) |

442 | |

443 | extern int32 mtx_assemble(mtx_matrix_t matrix); |

444 | /**< |

445 | *** Takes a matrix, assumed to have redundant and otherwise insane incidences |

446 | *** created by mtx_fill_value and sums all like entries, eliminating |

447 | *** the duplicates and the zeroes. Returns -# of duplicate elements removed. |

448 | *** returns 1 if fails for some reason. |

449 | *** @todo Could stand to have the error messages it emits improved. |

450 | *** @todo Could stand to take a rowrange or a rowlist, |

451 | *** a colrange or a collist,droptol. |

452 | *** Zeroes are not counted as duplicates. |

453 | *** algorithm cost: O(3*nnz) |

454 | **/ |

455 | |

456 | /* ********************************************************************* *\ |

457 | mtx element routines |

458 | None of these routines care about master/slave status. |

459 | \* ********************************************************************* */ |

460 | |

461 | extern void mtx_del_zr_in_row(mtx_matrix_t matrix, int32 row); |

462 | /**< |

463 | *** "Non-zeros" in the given row which are actually |

464 | *** zero are effectively removed (i.e. the status of "non-zero" is revoked). |

465 | -$- Does nothing to a bad matrix. |

466 | **/ |

467 | extern void mtx_del_zr_in_col(mtx_matrix_t matrix, int32 col); |

468 | /**< |

469 | *** "Non-zeros" in the given col which are actually |

470 | *** zero are effectively removed (i.e. the status of "non-zero" is revoked). |

471 | -$- Does nothing to a bad matrix. |

472 | **/ |

473 | extern void mtx_del_zr_in_rowrange(mtx_matrix_t matrix, mtx_range_t *rng); |

474 | /**< |

475 | *** "Non-zeros" in the given range of rows which are actually |

476 | *** zero are effectively removed (i.e. the status of "non-zero" is revoked). |

477 | -$- Does nothing to a bad matrix. |

478 | **/ |

479 | extern void mtx_del_zr_in_colrange(mtx_matrix_t matrix, mtx_range_t *rng); |

480 | /**< |

481 | *** "Non-zeros" in the given range of cols which are actually |

482 | *** zero are effectively removed (i.e. the status of "non-zero" is revoked). |

483 | -$- Does nothing to a bad matrix. |

484 | **/ |

485 | |

486 | extern void mtx_steal_org_row_vec(mtx_matrix_t mtx, int32 row, |

487 | real64 *vec, mtx_range_t *colrng); |

488 | /**< |

489 | *** The user is expected to supply the vec; we cannot check it. |

490 | *** Copies the mtx nonzeros currently within colrng INTO array vec which is |

491 | *** indexed by org column number. Does not affect other |

492 | *** entries of vec in or outside the range. In particular, vec |

493 | *** is NOT zeroed within the range unless there is a matrix element |

494 | *** with value zero at that location. |

495 | *** All incidence within colrng of the row given is removed from the matrix.<br><br> |

496 | *** |

497 | *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when |

498 | *** the row/col of interest is known to have incidence exclusively in |

499 | *** the range of interest.<br><br> |

500 | *** |

501 | -$- Fetches nothing from a bad matrix. |

502 | **/ |

503 | extern void mtx_steal_org_col_vec(mtx_matrix_t mtx, int32 col, |

504 | real64 *vec, mtx_range_t *rowrng); |

505 | /**< |

506 | *** The user is expected to supply the vec; we cannot check it. |

507 | *** Copies the mtx nonzeros currently within rowrng INTO array vec which is |

508 | *** indexed by org row number. Does not affect other |

509 | *** entries of vec in or outside the range. In particular, vec |

510 | *** is NOT zeroed within the range unless there is a matrix element |

511 | *** with value zero at that location. |

512 | *** All incidence within rowrng of the col given is removed from the matrix.<br><br> |

513 | *** |

514 | *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when |

515 | *** the row/col of interest is known to have incidence exclusively in |

516 | *** the range of interest.<br><br> |

517 | *** |

518 | -$- Fetches nothing from a bad matrix. |

519 | **/ |

520 | extern void mtx_steal_cur_row_vec(mtx_matrix_t mtx, int32 row, |

521 | real64 *vec, mtx_range_t *colrng); |

522 | /**< |

523 | *** The user is expected to supply the vec; we cannot check it. |

524 | *** Copies the mtx nonzeros currently within colrng INTO array vec which is |

525 | *** indexed by cur column number. Does not affect other |

526 | *** entries of vec in or outside the range. In particular, vec |

527 | *** is NOT zeroed within the range unless there is a matrix element |

528 | *** with value zero at that location. |

529 | *** All incidence within colrng of the row given is removed from the matrix.<br><br> |

530 | *** |

531 | *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when |

532 | *** the row/col of interest is known to have incidence exclusively in |

533 | *** the range of interest.<br><br> |

534 | *** |

535 | -$- Fetches nothing from a bad matrix. |

536 | **/ |

537 | extern void mtx_steal_cur_col_vec(mtx_matrix_t mtx, int32 col, |

538 | real64 *vec, mtx_range_t *rowrng); |

539 | /**< |

540 | *** The user is expected to supply the vec; we cannot check it. |

541 | *** Copies the mtx nonzeros currently within rowrng INTO array vec which is |

542 | *** indexed by cur row number. Does not affect other |

543 | *** entries of vec in or outside the range. In particular, vec |

544 | *** is NOT zeroed within the range unless there is a matrix element |

545 | *** with value zero at that location. |

546 | *** All incidence within rowrng of the col given is removed from the matrix.<br><br> |

547 | *** |

548 | *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when |

549 | *** the row/col of interest is known to have incidence exclusively in |

550 | *** the range of interest.<br><br> |

551 | *** |

552 | -$- Fetches nothing from a bad matrix. |

553 | **/ |

554 | |

555 | /*****************************************************************\ |

556 | Sparse vector operations, rather analogous to the mtx_value suite. |

557 | These are tools for data motion. No arithmetic operators |

558 | are provided as yet. The deallocation of sparse vectors is |

559 | the user's job. See the notes at the top of this header for the |

560 | data semantics of a sparse vector. |

561 | The user may construct a sparse vector. |

562 | Calls which return a sparse vector may create or use and return |

563 | a user supplied sparse vector. These calls are at liberty to |

564 | reallocate the data memory if that supplied is insufficient to |

565 | hold the data. The len and cap values of the vector will be reset |

566 | as appropriate. |

567 | |

568 | Functions do not create a sparse unless it says in their header |

569 | that mtx_CREATE_SPARSE is a valid argument. |

570 | \*****************************************************************/ |

571 | |

572 | extern boolean mtx_steal_org_row_sparse(mtx_matrix_t mtx, |

573 | int32 row, |

574 | mtx_sparse_t *sparse, |

575 | mtx_range_t *colrng); |

576 | /**< |

577 | *** Copies the mtx nonzeros currently within colrng to the sparse, |

578 | *** indexing by org column number. Nonzeros with value 0.0 WILL NOT |

579 | *** be included in the sparse. sparse->len will be set accordingly. |

580 | *** All incidence within colrng will be deleted from the mtx.<br><br> |

581 | *** |

582 | *** The user must supply the sparse; if it is too small, err will be |

583 | *** TRUE and data will not be collected and incidence not cleared. |

584 | *** mtx_CREATE_SPARSE is not a valid argument to this function. |

585 | *** What is too small? For all flavors the sparse must |

586 | *** have at least the capacity indicated by the col/rowrng.<br><br> |

587 | *** |

588 | *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when |

589 | *** the row/col of interest is known to have incidence exclusively in |

590 | *** the range of interest.<br><br> |

591 | *** |

592 | -$- Fetches nothing from a bad matrix. |

593 | **/ |

594 | extern boolean mtx_steal_org_col_sparse(mtx_matrix_t mtx, |

595 | int32 col, |

596 | mtx_sparse_t *sparse, |

597 | mtx_range_t *rowrng); |

598 | /**< |

599 | *** Copies the mtx nonzeros currently within rowrng to the sparse, |

600 | *** indexing by org rowumn number. Nonzeros with value 0.0 WILL NOT |

601 | *** be included in the sparse. sparse->len will be set accordingly. |

602 | *** All incidence within rowrng will be deleted from the mtx.<br><br> |

603 | *** |

604 | *** The user must supply the sparse; if it is too small, err will be |

605 | *** TRUE and data will not be collected and incidence not cleared. |

606 | *** mtx_CREATE_SPARSE is not a valid argument to this function. |

607 | *** What is too small? For all flavors the sparse must |

608 | *** have at least the capacity indicated by the row/colrng.<br><br> |

609 | *** |

610 | *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when |

611 | *** the row/col of interest is known to have incidence exclusively in |

612 | *** the range of interest.<br><br> |

613 | *** |

614 | -$- Fetches nothing from a bad matrix. |

615 | **/ |

616 | extern boolean mtx_steal_cur_row_sparse(mtx_matrix_t mtx, |

617 | int32 row, |

618 | mtx_sparse_t *sparse, |

619 | mtx_range_t *colrng); |

620 | /**< |

621 | *** Copies the mtx nonzeros currently within colrng to the sparse, |

622 | *** indexing by cur column number. Nonzeros with value 0.0 WILL NOT |

623 | *** be included in the sparse. sparse->len will be set accordingly. |

624 | *** All incidence within colrng will be deleted from the mtx.<br><br> |

625 | *** |

626 | *** The user must supply the sparse; if it is too small, err will be |

627 | *** TRUE and data will not be collected and incidence not cleared. |

628 | *** mtx_CREATE_SPARSE is not a valid argument to this function. |

629 | *** What is too small? For all flavors the sparse must |

630 | *** have at least the capacity indicated by the col/rowrng.<br><br> |

631 | *** |

632 | *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when |

633 | *** the row/col of interest is known to have incidence exclusively in |

634 | *** the range of interest.<br><br> |

635 | *** |

636 | -$- Fetches nothing from a bad matrix. |

637 | **/ |

638 | extern boolean mtx_steal_cur_col_sparse(mtx_matrix_t mtx, |

639 | int32 col, |

640 | mtx_sparse_t *sparse, |

641 | mtx_range_t *rowrng); |

642 | /**< |

643 | *** Copies the mtx nonzeros currently within rowrng to the sparse, |

644 | *** indexing by cur rowumn number. Nonzeros with value 0.0 WILL NOT |

645 | *** be included in the sparse. sparse->len will be set accordingly. |

646 | *** All incidence within rowrng will be deleted from the mtx.<br><br> |

647 | *** |

648 | *** The user must supply the sparse; if it is too small, err will be |

649 | *** TRUE and data will not be collected and incidence not cleared. |

650 | *** mtx_CREATE_SPARSE is not a valid argument to this function. |

651 | *** What is too small? For all flavors the sparse must |

652 | *** have at least the capacity indicated by the row/colrng.<br><br> |

653 | *** |

654 | *** Notes: It is rather faster to call this with mtx_ALL_COLS/ROWS when |

655 | *** the row/col of interest is known to have incidence exclusively in |

656 | *** the range of interest.<br><br> |

657 | *** |

658 | -$- Fetches nothing from a bad matrix. |

659 | **/ |

660 | |

661 | /* |

662 | extern wish ! ! ! NOT YET IMPLEMENTED. NO USE FOR THEM SO FAR. |

663 | extern void ! ! ! mtx_set_org_row_vec(mtx_matrix_t, int32, |

664 | real64 *, mtx_range_t *,boolean); |

665 | extern void ! ! ! mtx_set_org_col_vec(mtx_matrix_t, int32, |

666 | real64 *, mtx_range_t *,boolean); |

667 | extern void ! ! ! mtx_set_cur_row_vec(mtx_matrix_t, int32, |

668 | real64 *, mtx_range_t *,boolean); |

669 | extern void ! ! ! mtx_set_cur_col_vec(mtx_matrix_t, int32, |

670 | real64 *, mtx_range_t *,boolean); |

671 | -$- mtx_set_org_row_vec(mtx,row,vec,colrng,destructive) |

672 | -$- mtx_set_org_col_vec(mtx,col,vec,rowrng,destructive) |

673 | -$- mtx_set_cur_row_vec(mtx,row,vec,colrng,destructive) |

674 | -$- mtx_set_cur_col_vec(mtx,col,vec,rowrng,destructive) |

675 | *** mtx_matrix_t mtx; |

676 | *** int32 row,col; |

677 | *** real64 *vec; |

678 | *** mtx_range_t *colrng,*rowrng; |

679 | *** boolean destructive; |

680 | *** |

681 | *** mtx_set_org/cur_row_vec: |

682 | *** Copies the nonzeros currently within colrng FROM array vec which is |

683 | *** indexed by org/cur column number INTO the matrix. |

684 | *** If destructive is TRUE, existing nonzeros which are given value 0.0 |

685 | *** |

686 | *** mtx_set_org/cur_col_vec: |

687 | *** Switch row <--> col in above. |

688 | *** |

689 | *** Notes: It is faster to call this with a narrow range than with |

690 | *** mtx_ALL_COLS/ROWS. For ranges with very low sparsity, it may |

691 | *** be faster to call mtx_clear_row/col followed by mtx_fill_*_*_vec, |

692 | *** depending on the time cost of allocating and deallocating small |

693 | *** pieces of memory on the machine in question. |

694 | *** |

695 | ! ! Warning: If destructive is TRUE, care should be taken when using |

696 | ! ! these operators within a mtx_next_in_* loop that the current element |

697 | ! ! of the loop is not zeroed by the vec causing it to be deallocated. |

698 | *** |

699 | -$- Puts nothing to a bad matrix. |

700 | **/ |

701 | |

702 | extern void mtx_fill_org_row_vec(mtx_matrix_t mtx, int32 row, |

703 | real64 *vec, mtx_range_t *colrng); |

704 | /**< |

705 | *** Assumes that the colrng of row in the matrix is empty and |

706 | *** copies the nonzeros currently within colrng FROM array vec which is |

707 | *** indexed by org column number INTO the matrix.<br><br> |

708 | *** |

709 | *** Notes: It is faster to call this with a narrow range than with |

710 | *** mtx_ALL_COLS/ROWS. It is very marginally faster to call |

711 | *** mtx_fill_cur_row_vec() instead of this function.<br><br> |

712 | ! ! If you use this when the range is NOT empty, you will sooner or |

713 | ! ! later certainly lose numerical integrity and you may lose memory |

714 | ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br> |

715 | *** |

716 | -$- Puts nothing to a bad matrix. |

717 | **/ |

718 | extern void mtx_fill_org_col_vec(mtx_matrix_t mtx, int32 col, |

719 | real64 *vec, mtx_range_t *rowrng); |

720 | /**< |

721 | *** Assumes that the rowrng of col in the matrix is empty and |

722 | *** copies the nonzeros currently within rowrng FROM array vec which is |

723 | *** indexed by org row number INTO the matrix. |

724 | *** |

725 | *** Notes: It is faster to call this with a narrow range than with |

726 | *** mtx_ALL_COLS/ROWS. It is very marginally faster to call |

727 | *** mtx_fill_cur_col_vec() than this function.<br><br> |

728 | ! ! If you use this when the range is NOT empty, you will sooner or |

729 | ! ! later certainly lose numerical integrity and you may lose memory |

730 | ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br> |

731 | *** |

732 | -$- Puts nothing to a bad matrix. |

733 | **/ |

734 | extern void mtx_fill_cur_row_vec(mtx_matrix_t mtx, int32 row, |

735 | real64 *vec, mtx_range_t *colrng); |

736 | /**< |

737 | *** Assumes that the colrng of row in the matrix is empty and |

738 | *** copies the nonzeros currently within colrng FROM array vec which is |

739 | *** indexed by cur column number INTO the matrix.<br><br> |

740 | *** |

741 | *** Notes: It is faster to call this with a narrow range than with |

742 | *** mtx_ALL_COLS/ROWS. It is very marginally faster to call |

743 | *** this function instead of mtx_fill_org_row_vec().<br><br> |

744 | ! ! If you use this when the range is NOT empty, you will sooner or |

745 | ! ! later certainly lose numerical integrity and you may lose memory |

746 | ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br> |

747 | *** |

748 | -$- Puts nothing to a bad matrix. |

749 | **/ |

750 | extern void mtx_fill_cur_col_vec(mtx_matrix_t mtx, int32 col, |

751 | real64 *vec, mtx_range_t *rowrng); |

752 | /**< |

753 | *** Assumes that the rowrng of col in the matrix is empty and |

754 | *** copies the nonzeros currently within rowrng FROM array vec which is |

755 | *** indexed by cur row number INTO the matrix. |

756 | *** |

757 | *** Notes: It is faster to call this with a narrow range than with |

758 | *** mtx_ALL_COLS/ROWS. It is very marginally faster to call |

759 | *** this functions instead of mtx_fill_org_col_vec().<br><br> |

760 | ! ! If you use this when the range is NOT empty, you will sooner or |

761 | ! ! later certainly lose numerical integrity and you may lose memory |

762 | ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br> |

763 | *** |

764 | -$- Puts nothing to a bad matrix. |

765 | **/ |

766 | extern void mtx_dropfill_cur_row_vec(mtx_matrix_t mtx, int32 row, |

767 | real64 *vec, mtx_range_t *colrng, |

768 | real64 tolerance); |

769 | /**< |

770 | *** Assumes that the colrng of row in the matrix is empty and |

771 | *** copies the values such that abs(value) >tolerance currently |

772 | *** within colrng FROM array vec which is |

773 | *** indexed by cur row number INTO the matrix.<br><br> |

774 | *** |

775 | *** Notes: It is faster to call this with a narrow range than with |

776 | *** mtx_ALL_COLS/ROWS. |

777 | ! ! If you use this when the range is NOT empty, you will sooner or |

778 | ! ! later certainly lose numerical integrity and you may lose memory |

779 | ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br> |

780 | *** |

781 | -$- Puts nothing to a bad matrix. |

782 | **/ |

783 | extern void mtx_dropfill_cur_col_vec(mtx_matrix_t mtx, int32 col, |

784 | real64 *vec, mtx_range_t *rowrng, |

785 | real64 tolerance); |

786 | /**< |

787 | *** Assumes that the rowrng of col in the matrix is empty and |

788 | *** copies the values such that abs(value) >tolerance currently |

789 | *** within rowrng FROM array vec which is |

790 | *** indexed by cur column number INTO the matrix.<br><br> |

791 | *** |

792 | *** Notes: It is faster to call this with a narrow range than with |

793 | *** mtx_ALL_COLS/ROWS. |

794 | ! ! If you use this when the range is NOT empty, you will sooner or |

795 | ! ! later certainly lose numerical integrity and you may lose memory |

796 | ! ! integrity. The sparse matrix programmer cannot afford to be naive.<br><br> |

797 | *** |

798 | -$- Puts nothing to a bad matrix. |

799 | **/ |

800 | |

801 | extern void mtx_fill_org_row_sparse(mtx_matrix_t mtx, int32 row, |

802 | const mtx_sparse_t *sparse); |

803 | /**< |

804 | *** Fills the current row given with the data in the sparse given. |

805 | *** The indices in sp->idata are taken as org col indices. |

806 | *** It is assumed that the row is empty, at least where data is |

807 | *** being added.<br><br> |

808 | *** |

809 | *** This function ignores 0.0 in the data and does not create numbers |

810 | *** there in the mtx. |

811 | **/ |

812 | extern void mtx_fill_org_col_sparse(mtx_matrix_t mtx, int32 col, |

813 | const mtx_sparse_t *sparse); |

814 | /**< |

815 | *** Fills the current col given with the data in the sparse given. |

816 | *** The indices in sp->idata are taken as org row indices. |

817 | *** It is assumed that the col is empty, at least where data is |

818 | *** being added.<br><br> |

819 | *** |

820 | *** This function ignores 0.0 in the data and does not create numbers |

821 | *** there in the mtx. |

822 | **/ |

823 | extern void mtx_fill_cur_row_sparse(mtx_matrix_t mtx, int32 row, |

824 | const mtx_sparse_t *sparse); |

825 | /**< |

826 | *** Fills the current row given with the data in the sparse given. |

827 | *** The indices in sp->idata are taken as cur col indices. |

828 | *** It is assumed that the row is empty, at least where data is |

829 | *** being added.<br><br> |

830 | *** |

831 | *** This function ignores 0.0 in the data and does not create numbers |

832 | *** there in the mtx. |

833 | **/ |

834 | extern void mtx_fill_cur_col_sparse(mtx_matrix_t mtx, int32 col, |

835 | const mtx_sparse_t *sparse); |

836 | /**< |

837 | *** Fills the current col given with the data in the sparse given. |

838 | *** The indices in sp->idata are taken as cur row indices. |

839 | *** It is assumed that the col is empty, at least where data is |

840 | *** being added.<br><br> |

841 | *** |

842 | *** This function ignores 0.0 in the data and does not create numbers |

843 | *** there in the mtx. |

844 | **/ |

845 | |

846 | |

847 | extern void mtx_mult_row(mtx_matrix_t mtx, int32 row, |

848 | real64 factor, mtx_range_t *colrng); |

849 | /**< |

850 | *** Multiplies the given row by a given factor. Only those |

851 | *** elements with column index within the given range are multiplied. |

852 | *** This function tests for factor=0.0 and blows away the row if true. |

853 | -$- Does nothing on a bad matrix. |

854 | **/ |

855 | extern void mtx_mult_col(mtx_matrix_t mtx, int32 col, |

856 | real64 factor, mtx_range_t *rowrng); |

857 | /**< |

858 | *** Multiplies the given column by a given factor. Only those |

859 | *** elements with row index within the given range are multiplied. |

860 | *** This function tests for factor=0.0 and blows away the row if true. |

861 | -$- Does nothing on a bad matrix. |

862 | **/ |

863 | extern void mtx_mult_row_zero(mtx_matrix_t mtx, int32 row, |

864 | mtx_range_t *colrng); |

865 | /**< |

866 | *** Zeros the given row. Only those |

867 | *** elements with column index within the given range are zeroed. |

868 | *** This function zeros without disturbing structure. |

869 | -$- Does nothing on a bad matrix. |

870 | **/ |

871 | extern void mtx_mult_col_zero(mtx_matrix_t mtx, int32 col, |

872 | mtx_range_t *rowrng); |

873 | /**< |

874 | *** Zeros the given column. Only those |

875 | *** elements with row index within the given range are zeroed. |

876 | *** This function zeros without disturbing structure. |

877 | -$- Does nothing on a bad matrix. |

878 | **/ |

879 | |

880 | extern void mtx_add_row(mtx_matrix_t mtx, int32 srow, int32 trow, |

881 | real64 factor, mtx_range_t *colrng); |

882 | /**< |

883 | *** Adds a given multiple of row srow to row trow. |

884 | *** Only those elements with column index within the given range are |

885 | *** so affected.<br><br> |

886 | -$- Does nothing on a bad matrix. |

887 | **/ |

888 | extern void mtx_add_col(mtx_matrix_t mtx, int32 scol, int32 tcol, |

889 | real64 factor, mtx_range_t *rowrng); |

890 | /**< |

891 | *** Adds a given multiple of column scol to column tcol. |

892 | *** Only those elements with row index within the given range are |

893 | *** so affected.<br><br> |

894 | -$- Does nothing on a bad matrix. |

895 | **/ |

896 | |

897 | extern void mtx_add_row_series(int32 srow, real64 factor, |

898 | mtx_range_t *colrng); |

899 | /**< |

900 | *** Adds the given factor to row srow. |

901 | *** Only those elements of s with column index within the |

902 | *** given range are added to factor. |

903 | *** When possible, range mtx_ALL_COLS/ROWS is faster for sparse rows. |

904 | ! ! Calling this without a prior call to mtx_add_row_series_init() |

905 | ! ! is an error.<br><br> |

906 | *** |

907 | ! ! Warning: You MUST release any grabbed row/col created on a matrix |

908 | ! ! before destroying that matrix. Failure to do so is fatal.<br><br><br><br> |

909 | *** |

910 | -$- Does nothing on a bad matrix. |

911 | **/ |

912 | extern void mtx_add_col_series(int32 scol, real64 factor, |

913 | mtx_range_t *rowrng); |

914 | /**< |

915 | *** Adds the given factor to column scol. |

916 | *** Only those elements of s with row index within the |

917 | *** given range are added to factor. |

918 | *** When possible, range mtx_ALL_COLS/ROWS is faster for sparse rows. |

919 | ! ! Calling this without a prior call to mtx_add_col_series_init() |

920 | ! ! is an error.<br><br> |

921 | *** |

922 | ! ! Warning: You MUST release any grabbed row/col created on a matrix |

923 | ! ! before destroying that matrix. Failure to do so is fatal.<br><br><br><br> |

924 | *** |

925 | -$- Does nothing on a bad matrix. |

926 | **/ |

927 | extern void mtx_add_row_series_init(mtx_matrix_t mtx, int32 trow, |

928 | boolean userow); |

929 | /**< |

930 | *** Grab or release elements depending on the value of trow.<br><br> |

931 | *** |

932 | *** If t>=0, grab a row trow of the matrix to have several rows |

933 | *** from the same matrix added to it. userow is ignored for t>=0. |

934 | *** Only one row at a time may be grabbed for all existing |

935 | *** matrices. (One row and one col may be grabbed contemporaneously.) |

936 | *** You must release the row (see below) before you can grab another.<br><br> |

937 | *** |

938 | *** If t is mtx_NONE, release the last row which was grabbed for multiple adds. |

939 | *** If userow is TRUE, the current contents of row trow |

940 | *** (from the previous call) will be used to release the row. |

941 | *** If userow is FALSE, a pessimistic release method will be |

942 | *** used instead of the row previously specified.<br><br> |

943 | ! ! If ANY destructive operations have been done on the row, call |

944 | ! ! this with userow==FALSE. |

945 | ! ! The mtx given to a release call must match that given in the grabbing |

946 | ! ! or the release is ignored. |

947 | *** For very dense rows, it may be faster to call with userow |

948 | *** == FALSE since the release with TRUE requires a row traversal.<br><br> |

949 | *** |

950 | ! ! Warning: You MUST release any grabbed row created on a matrix |

951 | ! ! before destroying that matrix. Failure to do so is fatal.<br><br> |

952 | *** |

953 | -$- Does nothing on a bad matrix. |

954 | **/ |

955 | extern void mtx_add_col_series_init(mtx_matrix_t mtx, int32 tcol, |

956 | boolean usecol); |

957 | /**< |

958 | *** Grab or release elements depending on the value of tcol.<br><br> |

959 | *** |

960 | *** If t>=0, grab a column tcol of the matrix to have several columns |

961 | *** from the same matrix added to it. usecol is ignored for t>=0. |

962 | *** Only one column at a time may be grabbed for all existing |

963 | *** matrices. (One row and one col may be grabbed contemporaneously.) |

964 | *** You must release the column (see below) before you can grab another.<br><br> |

965 | *** |

966 | *** If t is mtx_NONE, release the last column which was grabbed for multiple adds. |

967 | *** If usecol is TRUE, the current contents of column tcol |

968 | *** (from the previous call) will be used to release the column. |

969 | *** If usecol is FALSE, a pessimistic release method will be |

970 | *** used instead of the column previously specified.<br><br> |

971 | ! ! If ANY destructive operations have been done on the column, call |

972 | ! ! this with usecol==FALSE. |

973 | ! ! The mtx given to a release call must match that given in the grabbing |

974 | ! ! or the release is ignored. |

975 | *** For very dense columns, it may be faster to call with usecol |

976 | *** == FALSE since the release with TRUE requires a column traversal.<br><br> |

977 | *** |

978 | ! ! Warning: You MUST release any grabbed column created on a matrix |

979 | ! ! before destroying that matrix. Failure to do so is fatal.<br><br> |

980 | *** |

981 | -$- Does nothing on a bad matrix. |

982 | **/ |

983 | /* OLD GROUP COMMENT */ |

984 | /* |

985 | -$- mtx_add_row_series(srow,factor,colrng) |

986 | -$- mtx_add_col_series(scol,factor,rowrng) |

987 | -$- mtx_add_row_series_init(matrix,trow,userow) |

988 | -$- mtx_add_col_series_init(matrix,tcol,usecol) |

989 | *** mtx_matrix_t matrix; |

990 | *** int32 srow,trow,scol,tcol; |

991 | *** real64 factor; |

992 | *** mtx_range_t *colrng,*rowrng; |

993 | *** boolean userow,usecol; |

994 | *** |

995 | *** mtx_add_row/col_series_init(mtx, t>=0, bool): |

996 | *** Grab a row/column t of the matrix to have several rows/columns |

997 | *** from the same matrix added to it. bool is ignored for t>=0. |

998 | *** Only one row/col at a time may be grabbed for all existing |

999 | *** matrices. (One row and one col may be grabbed contemporaneously.) |

1000 | *** You must release the row/col (see below) before you can grab another. |

1001 | *** |

1002 | *** mtx_add_row/col_series_init(mtx, mtx_NONE, userow/col): |

1003 | *** Release the last row/column which was grabbed for multiple adds. |

1004 | *** If userow/col is TRUE, the current contents of row/col t |

1005 | *** (from the previous call) will be used to release the row/col. |

1006 | *** If userow/col is FALSE, a pessimistic release method will be |

1007 | *** used instead of the row/col previously specified. |

1008 | ! ! If ANY destructive operations have been done on the row/col, call |

1009 | ! ! this with userow/col==FALSE. |

1010 | ! ! The mtx given to a release call must match that given in the grabbing |

1011 | ! ! or the release is ignored. |

1012 | *** For very dense rows/cols, it may be faster to call with userow/col |

1013 | *** == FALSE since the release with TRUE requires a row/col traversal. |

1014 | *** |

1015 | *** mtx_add_row/col_series(s,factor,rowrng) |

1016 | *** Adds the given multiple of row/column s to trow/tcol. |

1017 | *** Only those elements of s with column/row index within the |

1018 | *** given range are added to trow/tcol. |

1019 | *** When possible, range mtx_ALL_COLS/ROWS is faster for sparse rows. |

1020 | ! ! Calling these without a prior call to series_init is an error. |

1021 | *** |

1022 | ! ! Warning: You MUST release any grabbed row/col created on a matrix |

1023 | ! ! before destroying that matrix. Failure to do so is fatal. |

1024 | *** |

1025 | -$- Does nothing on a bad matrix. |

1026 | **/ |

1027 | |

1028 | /* |

1029 | extern wish ! ! ! NOT YET IMPLEMENTED. NO USE FOR THEM SO FAR. |

1030 | extern void ! ! ! mtx_add_row_org_vec(mtx_matrix_t,int32, |

1031 | real64 *,real64, |

1032 | mtx_range_t *, boolean); |

1033 | extern void ! ! ! mtx_add_col_org_vec(mtx_matrix_t,int32, |

1034 | real64 *,real64, |

1035 | mtx_range_t *, boolean); |

1036 | extern void ! ! ! mtx_add_row_cur_vec(mtx_matrix_t,int32, |

1037 | real64 *,real64, |

1038 | mtx_range_t *, boolean); |

1039 | extern void ! ! ! mtx_add_col_cur_vec(mtx_matrix_t,int32, |

1040 | real64 *,real64, |

1041 | mtx_range_t *, boolean); |

1042 | -$- mtx_add_row_org_vec(matrix,trow,svec,factor,colrng,transpose) |

1043 | -$- mtx_add_col_org_vec(matrix,tcol,svec,factor,rowrng,transpose) |

1044 | -$- mtx_add_row_cur_vec(matrix,trow,svec,factor,colrng,transpose) |

1045 | -$- mtx_add_col_cur_vec(matrix,tcol,svec,factor,rowrng,transpose) |

1046 | *** mtx_matrix_t matrix; |

1047 | *** int32 trow,tcol; |

1048 | *** real64 *svec; |

1049 | *** real64 factor; |

1050 | *** mtx_range_t *colrng,*rowrng; |

1051 | *** boolean transpose; |

1052 | *** |

1053 | *** mtx_add_row_org/cur_vec: |

1054 | *** In matrix trow[col] += factor*svec[col] for elements of svec in colrng. |

1055 | *** svec is org/cur indexed, by row if !transpose and by column if transpose. |

1056 | *** |

1057 | *** mtx_add_col_org/cur_vec: |

1058 | *** Reverse row <-->col in above |

1059 | *** |

1060 | *** This is an absurdly expensive thing to do. Think very carefully about |

1061 | *** whether you are ignoring existing sparsity info before asking that this |

1062 | *** mtx primitive be coded. |

1063 | -$- Does nothing on a bad matrix. |

1064 | **/ |

1065 | |

1066 | extern void mtx_old_add_row_sparse(mtx_matrix_t mtx, int32 row, |

1067 | real64 *drow, real64 factor, |

1068 | mtx_range_t *colrng, int32 *collist); |

1069 | /**< |

1070 | *** Adds factor*(drow)[j] to row. |

1071 | *** Drow is assumed to be the size of the matrix and in current |

1072 | *** row order, not original order.<br><br> |

1073 | *** |

1074 | *** If colrng is mtx_ALL_COLS, then the following is TRUE: |

1075 | *** If collist is NOT NULL, it will be used instead of colrng |

1076 | *** to determine which columns j of drow are added to row. |

1077 | *** Collist must be an array terminated by -1. The sanity of |

1078 | *** current indices in collist is the users responsibility. |

1079 | *** In particular, in list mode the value of drow is added blindly |

1080 | *** rather than being checked for 0.0 and the range of indices is not |

1081 | *** checked against the matrix size. |

1082 | *** If collist IS NULL the range will be mtx_ALL_COLS. |

1083 | *** If a range is specified, collist is ignored and only those |

1084 | *** elements with column index j within the given range are affected.<br><br> |

1085 | *** |

1086 | *** List mode is faster if you are adding the same dense vector |

1087 | *** (differing only by factor) across many (>2) rows/columns. |

1088 | *** Range mode is more convenient. The caller should switch between the |

1089 | *** two as appropriate.<br><br> |

1090 | -$- Does nothing on a bad matrix. |

1091 | *** |

1092 | *** @todo The interface of this operator needs some work! |

1093 | *** In particular, it should be redone with consideration given |

1094 | *** to the mtx_sparse_t recently added. |

1095 | **/ |

1096 | extern void mtx_old_add_col_sparse(mtx_matrix_t mtx, int32 col, |

1097 | real64 *dcol, real64 factor, |

1098 | mtx_range_t *rowrng, int32 *rowlist); |

1099 | /**< |

1100 | *** Adds factor*(dcol)[j] to col. |

1101 | *** Dcol is assumed to be the size of the matrix and in current |

1102 | *** column order, not original order.<br><br> |

1103 | *** |

1104 | *** If rowrng is mtx_ALL_ROWS, then the following is TRUE: |

1105 | *** If rowlist is NOT NULL, it will be used instead of rowrng |

1106 | *** to determine which rows j of dcol are added to col. |

1107 | *** Rowlist must be an array terminated by -1. The sanity of |

1108 | *** current indices in rowlist is the users responsibility. |

1109 | *** In particular, in list mode the value of dcol is added blindly |

1110 | *** rather than being checked for 0.0 and the range of indices is not |

1111 | *** checked against the matrix size. |

1112 | *** If rowlist IS NULL the range will be mtx_ALL_ROWS. |

1113 | *** If a range is specified, rowlist is ignored and only those |

1114 | *** elements with row index j within the given range are affected.<br><br> |

1115 | *** |

1116 | *** List mode is faster if you are adding the same dense vector |

1117 | *** (differing only by factor) across many (>2) rows/columns. |

1118 | *** Range mode is more convenient. The caller should switch between the |

1119 | *** two as appropriate.<br><br> |

1120 | -$- Does nothing on a bad matrix. |

1121 | *** |

1122 | *** @todo The interface of this operator needs some work! |

1123 | *** In particular, it should be redone with consideration given |

1124 | *** to the mtx_sparse_t recently added. |

1125 | **/ |

1126 | /* OLD GROUP COMMENT */ |

1127 | /* |

1128 | *** Note: the interface of this operator needs some work! |

1129 | *** In particular, it should be redone with consideration given |

1130 | *** to the mtx_sparse_t recently added. |

1131 | *** |

1132 | -$- mtx_old_add_row_sparse(matrix,row,drow,factor,colrng,collist) |

1133 | -$- mtx_old_add_col_sparse(matrix,col,dcol,factor,rowrng,rowlist) |

1134 | *** mtx_matrix_t matrix; |

1135 | *** int32 row,col,*collist,*rowlist; |

1136 | *** real64 *drow, *dcol; |

1137 | *** real64 factor; |

1138 | *** mtx_range_t *colrng,*rowrng; |

1139 | *** |

1140 | *** Dense in these function names refers to the row/col data type, |

1141 | *** a vector as opposed to an mtx row/col, not the information density. |

1142 | *** Adds factor*(drow/dcol)[j] to row/col. |

1143 | *** Drow/dcol are assumed to be the size of the matrix and in current |

1144 | *** row/col order, not original order. |

1145 | *** |

1146 | *** If colrng/rowrng is mtx_ALL_COLS/ROWS, then the following is TRUE: |

1147 | *** If collist/rowlist is NOT NULL, it will be used instead of the rng |

1148 | *** to determine which columns/rows j of drow/dcol are added to row/col. |

1149 | *** Collist/rowlist must be an array terminated by -1. The sanity of |

1150 | *** current indices in collist/rowlist is the users responsibility. |

1151 | *** In particular, in list mode the value of drow/dcol is added blindly |

1152 | *** rather than being checked for 0.0 and the range of indices is not |

1153 | *** checked against the matrix size. |

1154 | *** If collist/rowlist IS NULL the range will be mtx_ALL_COLS/ROWS. |

1155 | *** If a range is specified, collist/rowlist is ignored and only those |

1156 | *** elements with column/row index j within the given range are affected. |

1157 | *** |

1158 | *** List mode is faster if you are adding the same dense vector |

1159 | *** (differing only by factor) across many (>2) rows/columns. |

1160 | *** Range mode is more convenient. The caller should switch between the |

1161 | *** two as appropriate. |

1162 | -$- Does nothing on a bad matrix. |

1163 | **/ |

1164 | |

1165 | extern void mtx_add_row_sparse(mtx_matrix_t mtx, int32 row, |

1166 | real64 factor, mtx_sparse_t *sparse); |

1167 | /**< @todo mtx_add_row_sparse() NOT IMPLEMENTED. */ |

1168 | extern void mtx_add_col_sparse(mtx_matrix_t mtx, int32 col, |

1169 | real64 factor, mtx_sparse_t *sparse); |

1170 | /**< @todo mtx_add_col_sparse() NOT IMPLEMENTED. */ |

1171 | |

1172 | extern size_t mtx_size(mtx_matrix_t mtx); |

1173 | /**< |

1174 | *** Returns the amount of memory in use by a matrix and all its |

1175 | *** bits and pieces. |

1176 | *** Slaves report only their incremental cost, that is they do |

1177 | *** not report the cost of the structures they share with a master. |

1178 | *** Masters do report the cost of their slaves. |

1179 | **/ |

1180 | extern size_t mtx_chattel_size(mtx_matrix_t mtx); |

1181 | /**< |

1182 | *** Returns the memory used by all slaves of the matrix given |

1183 | *** that is not shared with the master. Returns 0 from a slave. |

1184 | **/ |

1185 | |

1186 | extern void mtx_free_reused_mem(void); |

1187 | /**< |

1188 | *** Deallocates any memory that mtx may be squirrelling away for |

1189 | *** internal reuse. Calling this while any slv_system_t exists |

1190 | *** is likely to be fatal: handle with care. |

1191 | **/ |

1192 | |

1193 | /* ********************************************************************* *\ |

1194 | mtx io routines |

1195 | \* ********************************************************************* */ |

1196 | extern void mtx_write_sparse(FILE *file, mtx_sparse_t *sparse); |

1197 | /**< |

1198 | *** Outputs sizes and data of sparse vector to the file given. |

1199 | **/ |

1200 | |

1201 | extern void mtx_write_region_human_f(FILE *file, |

1202 | mtx_matrix_t mtx, |

1203 | mtx_region_t *region, |

1204 | int colwise, |

1205 | int orgwise); |

1206 | /**< |

1207 | Internal function to output a matrix region to file. |

1208 | Implementation function for the intended user-callable functions |

1209 | - mtx_write_region_human() |

1210 | - mtx_write_region_human_rows() |

1211 | - mtx_write_region_human_cols() |

1212 | - mtx_write_region_human_orgrows() |

1213 | - mtx_write_region_human_orgcols() |

1214 | |

1215 | Outputs permutation and values of the nonzero elements in the |

1216 | given region of the mtx to the file given. |

1217 | If colwise != 0, output will be column grouped, |

1218 | otherwise it will be row grouped. |

1219 | If orgwise != 0, only org indices will be printed. |

1220 | Doesn't care about master/slave status. |

1221 | */ |

1222 | |

1223 | #define mtx_write_region_human(f,m,r) mtx_write_region_human_f((f),(m),(r),0,0) |

1224 | /**< |

1225 | Grandfather support for the old usages. |

1226 | @see mtx_write_region_human_f(). |

1227 | */ |

1228 | #define mtx_write_region_human_rows(f,m,r) \ |

1229 | mtx_write_region_human_f((f),(m),(r),0,0) |

1230 | /**< |

1231 | Writes row oriented human readable output of a mtx region. |

1232 | @see mtx_write_region_human_f(). |

1233 | */ |

1234 | #define mtx_write_region_human_cols(f,m,r) \ |

1235 | mtx_write_region_human_f((f),(m),(r),1,0) |

1236 | /**< |

1237 | Writes column oriented human readable output of a mtx region. |

1238 | @see mtx_write_region_human_f(). |

1239 | */ |

1240 | #define mtx_write_region_human_orgrows(f,m,r) \ |

1241 | mtx_write_region_human_f((f),(m),(r),0,1) |

1242 | /**< |

1243 | Writes row oriented human readable output of a mtx region. |

1244 | @see mtx_write_region_human_f(). |

1245 | */ |

1246 | #define mtx_write_region_human_orgcols(f,m,r) \ |

1247 | mtx_write_region_human_f((f),(m),(r),1,1) |

1248 | /**< |

1249 | Writes column oriented human readable output of a mtx region. |

1250 | @see mtx_write_region_human_f(). |

1251 | */ |

1252 | |

1253 | ASC_DLLSPEC void mtx_write_region(FILE *file, |

1254 | mtx_matrix_t mtx, |

1255 | mtx_region_t *region); |

1256 | /**< |

1257 | Outputs permutation and values of the nonzero elements in the |

1258 | given region of the mtx to the file given along with the matrix |

1259 | size. |

1260 | The coordinates of the nonzeros written will be in original |

1261 | (unpermuted) indexing. This file is for mtx_read_region, but is |

1262 | in ASCII for portability. |

1263 | Doesn't care about master/slave status.<br><br> |

1264 | Not intended for human consumptions, but just so you know |

1265 | permutations are written in order r2org org2r c2org org2c. |

1266 | parity is not written.<br><br> |

1267 | If the region given is mtx_ENTIRE_MATRIX, and there is a |

1268 | block structure present in the matrix, it will be written as well |

1269 | and the symbolic rank will go out with the block structure. |

1270 | */ |

1271 | |

1272 | extern mtx_matrix_t mtx_read_region(FILE *file, |

1273 | mtx_matrix_t mtx, |

1274 | int transposed); |

1275 | /**< |

1276 | *** Reads a matrix region. |

1277 | *** From the file pointer, does the following: |

1278 | *** - Gets the matrix order of the data in the file. |

1279 | *** - If mtx is NULL, creates it. |

1280 | *** - Expands the matrix given or created to the data order if it is too small. |

1281 | *** - Permutes the matrix to the permutation found in the file. |

1282 | *** - Reads the region limits in the file and clears that region in the mtx. |

1283 | *** - Reads coefficients from the file. |

1284 | *** |

1285 | *** transposed governs if the matrix data should be treated as |

1286 | *** row col or col row |

1287 | ! ! Warnings: Do not add incidence data to the |

1288 | ! ! file except in those org_rows and org_cols which are within the |

1289 | ! ! region specified (note that the region is given in CUR coordinates.) |

1290 | ! ! Adding incidence outside the region may lead to loss of internal |

1291 | ! ! consistency unless the entire mtx given is empty when this is called. |

1292 | ! ! If you send a matrix larger than the order of data in the file, |

1293 | ! ! you should do a reset to it first to undo the previous permutation.<br><br> |

1294 | *** |

1295 | *** Return value is the pointer to the mtx given or created. |

1296 | *** If error in reading matrix file, mtx returned may be incomplete or NULL |

1297 | *** if the mtx given was NULL. |

1298 | *** If the file read has block information in it and further the user sent |

1299 | *** in NULL to this function, block info will be read and added to the |

1300 | *** returned matrix.<br><br> |

1301 | *** |

1302 | *** Doesn't care about master/slave status. |

1303 | **/ |

1304 | |

1305 | ASC_DLLSPEC void mtx_write_region_matlab(FILE *file, |

1306 | mtx_matrix_t mtx, |

1307 | mtx_region_t *region); |

1308 | /**< |

1309 | Outputs values of the nonzero elements in the |

1310 | given region of the mtx to the file in matlab/harwell sparse format. |

1311 | The "a=[\n" and trailing "];\n" are not supplied, since the caller |

1312 | knows better what they should look like. |

1313 | Row/column coordinates printed are the cur coordinates. |

1314 | */ |

1315 | |

1316 | ASC_DLLSPEC int mtx_write_region_mmio(FILE *file |

1317 | ,mtx_matrix_t mtx, mtx_region_t *region); |

1318 | /**< |

1319 | Outputs values of the nonzero elements in the |

1320 | given region of the mtx to the file in Matrix Market sparse format |

1321 | Row/column coordinates printed are the 'cur' coordinates. |

1322 | |

1323 | @param region Set to mtx_ENTIRE_MATRIX for the entire matrix to be output |

1324 | @param file Could be stderr, stdout, or a file pointer that you have opened |

1325 | @return 0 on success |

1326 | @see ASC_WITH_MMIO |

1327 | */ |

1328 | |

1329 | ASC_DLLSPEC void mtx_write_region_plot(FILE *file, |

1330 | mtx_matrix_t mtx, mtx_region_t *region); |

1331 | /**< |

1332 | Outputs the coordinates of elements to file with format suitable |

1333 | for xgraph consumption from the given region of the mtx. |

1334 | A suitable xgraph invocation would be "xgraph -nl -m filename". |

1335 | Doesn't care about master/slave status. |

1336 | */ |

1337 | |

1338 | ASC_DLLSPEC void mtx_write_region_csr(FILE *file, |

1339 | mtx_matrix_t mtx, mtx_region_t *region, int offset); |

1340 | /**< |

1341 | This function writes out the matrix in compressed row format. |

1342 | There may be a _ccs version (column based) one day. |

1343 | Doesn't care about master/slave status. |

1344 | */ |

1345 | |

1346 | ASC_DLLSPEC void mtx_write_region_smms(FILE *file, |

1347 | mtx_matrix_t mtx, mtx_region_t *region, int offset); |

1348 | /**< |

1349 | The _smms version writes out the matrix in a form digestible by |

1350 | Alvarado's Sparse Matrix Manipulation System. |

1351 | Doesn't care about master/slave status. |

1352 | |

1353 | Writes the given region of the matrix to the named file. |

1354 | Will write the entire matrix if the region is mtx_ENTIRE_MATRIX. |

1355 | offset controls whether fortran (1) or c style indexing is done. |

1356 | |

1357 | @NOTE I contacted Alvarado about his code and he's trying to dig it up. |

1358 | At present it's not available anywhere. |

1359 | |

1360 | @see http://citeseer.ist.psu.edu/366279.html |

1361 | */ |

1362 | |

1363 | extern mtx_matrix_t mtx_read_smms(FILE *file, |

1364 | mtx_matrix_t mtx, int transpose); |

1365 | /**< |

1366 | Reads a matrix in smms format. If a NULL matrix |

1367 | is sent in, it will create and return it. If a non NULL matrix |

1368 | is given, the order will be increased if necessary. The contents |

1369 | of the old mtx, will be blown away. The transpose flag dictates |

1370 | whether the transpose should be read in. |

1371 | Doesn't care about master/slave status. |

1372 | */ |

1373 | |

1374 | extern void mtx_exception_recover(void); |

1375 | /**< |

1376 | Cleans up after a floating point exception has |

1377 | occurred during matrix manipulations. You don't need to know |

1378 | what this does, except that you should call it any time this may |

1379 | have occurred. Several functions use |

1380 | data structures that can cause insanity in the event of exception.<br><br> |

1381 | |

1382 | Just for the curious, it resets several internal data structures |

1383 | needed including ones used in the operators: |

1384 | - mtx_add_row/col() |

1385 | - mtx_add_row/col_series() |

1386 | - mtx_add_row/col_series_init() |

1387 | - mtx_assemble() |

1388 | - mtx_add_outer_product() |

1389 | */ |

1390 | |

1391 | ASC_DLLSPEC void mtx__debug_output(FILE *file, mtx_matrix_t mtx); |

1392 | /**< |

1393 | Debug-outputs all internal information about a matrix to file. |

1394 | In the process, integrity checks are performed. |

1395 | If file is NULL, output goes to default (which is stderr.) |

1396 | Doesn't care about master/slave status. |

1397 | */ |

1398 | |

1399 | /** @} */ |

1400 | |

1401 | #endif /**< ASC_MTX_BASIC_H */ |

john.pye@anu.edu.au | ViewVC Help |

Powered by ViewVC 1.1.22 |