1 /****************************************************************************** 2 * Copyright 1998-2019 Lawrence Livermore National Security, LLC and other 3 * HYPRE Project Developers. See the top-level COPYRIGHT file for details. 4 * 5 * SPDX-License-Identifier: (Apache-2.0 OR MIT) 6 ******************************************************************************/ 7 8 #ifndef HYPRE_STRUCT_MV_HEADER 9 #define HYPRE_STRUCT_MV_HEADER 10 11 #include "HYPRE_utilities.h" 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /* forward declarations */ 18 #ifndef HYPRE_StructVector_defined 19 #define HYPRE_StructVector_defined 20 struct hypre_StructVector_struct; 21 typedef struct hypre_StructVector_struct *HYPRE_StructVector; 22 #endif 23 24 /*-------------------------------------------------------------------------- 25 *--------------------------------------------------------------------------*/ 26 27 /** 28 * @defgroup StructSystemInterface Struct System Interface 29 * 30 * This interface represents a structured-grid conceptual view of a linear 31 * system. 32 * 33 * @memo A structured-grid conceptual interface 34 * 35 * @{ 36 **/ 37 38 /*-------------------------------------------------------------------------- 39 *--------------------------------------------------------------------------*/ 40 41 /** 42 * @name Struct Grids 43 * 44 * @{ 45 **/ 46 47 struct hypre_StructGrid_struct; 48 /** 49 * A grid object is constructed out of several "boxes", defined on a global 50 * abstract index space. 51 **/ 52 typedef struct hypre_StructGrid_struct *HYPRE_StructGrid; 53 54 /** 55 * Create an <em>ndim</em>-dimensional grid object. 56 **/ 57 HYPRE_Int HYPRE_StructGridCreate(MPI_Comm comm, 58 HYPRE_Int ndim, 59 HYPRE_StructGrid *grid); 60 61 /** 62 * Destroy a grid object. An object should be explicitly destroyed using this 63 * destructor when the user's code no longer needs direct access to it. Once 64 * destroyed, the object must not be referenced again. Note that the object may 65 * not be deallocated at the completion of this call, since there may be 66 * internal package references to the object. The object will then be destroyed 67 * when all internal reference counts go to zero. 68 **/ 69 HYPRE_Int HYPRE_StructGridDestroy(HYPRE_StructGrid grid); 70 71 /** 72 * Set the extents for a box on the grid. 73 **/ 74 HYPRE_Int HYPRE_StructGridSetExtents(HYPRE_StructGrid grid, 75 HYPRE_Int *ilower, 76 HYPRE_Int *iupper); 77 78 /** 79 * Finalize the construction of the grid before using. 80 **/ 81 HYPRE_Int HYPRE_StructGridAssemble(HYPRE_StructGrid grid); 82 83 /** 84 * Set the periodicity for the grid. 85 * 86 * The argument \e periodic is an <em>ndim</em>-dimensional integer array that 87 * contains the periodicity for each dimension. A zero value for a dimension 88 * means non-periodic, while a nonzero value means periodic and contains the 89 * actual period. For example, periodicity in the first and third dimensions 90 * for a 10x11x12 grid is indicated by the array [10,0,12]. 91 * 92 * NOTE: Some of the solvers in hypre have power-of-two restrictions on the size 93 * of the periodic dimensions. 94 **/ 95 HYPRE_Int HYPRE_StructGridSetPeriodic(HYPRE_StructGrid grid, 96 HYPRE_Int *periodic); 97 98 /** 99 * Set the ghost layer in the grid object 100 **/ 101 HYPRE_Int HYPRE_StructGridSetNumGhost(HYPRE_StructGrid grid, 102 HYPRE_Int *num_ghost); 103 104 /**@}*/ 105 106 /*-------------------------------------------------------------------------- 107 *--------------------------------------------------------------------------*/ 108 109 /** 110 * @name Struct Stencils 111 * 112 * @{ 113 **/ 114 115 struct hypre_StructStencil_struct; 116 /** 117 * The stencil object. 118 **/ 119 typedef struct hypre_StructStencil_struct *HYPRE_StructStencil; 120 121 /** 122 * Create a stencil object for the specified number of spatial dimensions and 123 * stencil entries. 124 **/ 125 HYPRE_Int HYPRE_StructStencilCreate(HYPRE_Int ndim, 126 HYPRE_Int size, 127 HYPRE_StructStencil *stencil); 128 129 /** 130 * Destroy a stencil object. 131 **/ 132 HYPRE_Int HYPRE_StructStencilDestroy(HYPRE_StructStencil stencil); 133 134 /** 135 * Set a stencil entry. 136 * 137 * NOTE: The name of this routine will eventually be changed to \e 138 * HYPRE\_StructStencilSetEntry. 139 **/ 140 HYPRE_Int HYPRE_StructStencilSetElement(HYPRE_StructStencil stencil, 141 HYPRE_Int entry, 142 HYPRE_Int *offset); 143 144 /**@}*/ 145 146 /*-------------------------------------------------------------------------- 147 *--------------------------------------------------------------------------*/ 148 149 /** 150 * @name Struct Matrices 151 * 152 * @{ 153 **/ 154 155 struct hypre_StructMatrix_struct; 156 /** 157 * The matrix object. 158 **/ 159 typedef struct hypre_StructMatrix_struct *HYPRE_StructMatrix; 160 161 /** 162 * Create a matrix object. 163 **/ 164 HYPRE_Int HYPRE_StructMatrixCreate(MPI_Comm comm, 165 HYPRE_StructGrid grid, 166 HYPRE_StructStencil stencil, 167 HYPRE_StructMatrix *matrix); 168 169 /** 170 * Destroy a matrix object. 171 **/ 172 HYPRE_Int HYPRE_StructMatrixDestroy(HYPRE_StructMatrix matrix); 173 174 /** 175 * Prepare a matrix object for setting coefficient values. 176 **/ 177 HYPRE_Int HYPRE_StructMatrixInitialize(HYPRE_StructMatrix matrix); 178 179 /** 180 * Set matrix coefficients index by index. The \e values array is of length 181 * \e nentries. 182 * 183 * NOTE: For better efficiency, use \ref HYPRE_StructMatrixSetBoxValues to set 184 * coefficients a box at a time. 185 **/ 186 HYPRE_Int HYPRE_StructMatrixSetValues(HYPRE_StructMatrix matrix, 187 HYPRE_Int *index, 188 HYPRE_Int nentries, 189 HYPRE_Int *entries, 190 HYPRE_Complex *values); 191 192 /** 193 * Add to matrix coefficients index by index. The \e values array is of 194 * length \e nentries. 195 * 196 * NOTE: For better efficiency, use \ref HYPRE_StructMatrixAddToBoxValues to 197 * set coefficients a box at a time. 198 **/ 199 HYPRE_Int HYPRE_StructMatrixAddToValues(HYPRE_StructMatrix matrix, 200 HYPRE_Int *index, 201 HYPRE_Int nentries, 202 HYPRE_Int *entries, 203 HYPRE_Complex *values); 204 205 /** 206 * Set matrix coefficients which are constant over the grid. The \e values 207 * array is of length \e nentries. 208 **/ 209 HYPRE_Int HYPRE_StructMatrixSetConstantValues(HYPRE_StructMatrix matrix, 210 HYPRE_Int nentries, 211 HYPRE_Int *entries, 212 HYPRE_Complex *values); 213 /** 214 * Add to matrix coefficients which are constant over the grid. The \e 215 * values array is of length \e nentries. 216 **/ 217 HYPRE_Int HYPRE_StructMatrixAddToConstantValues(HYPRE_StructMatrix matrix, 218 HYPRE_Int nentries, 219 HYPRE_Int *entries, 220 HYPRE_Complex *values); 221 222 /** 223 * Set matrix coefficients a box at a time. The data in \e values is ordered 224 * as follows: 225 * 226 \verbatim 227 m = 0; 228 for (k = ilower[2]; k <= iupper[2]; k++) 229 for (j = ilower[1]; j <= iupper[1]; j++) 230 for (i = ilower[0]; i <= iupper[0]; i++) 231 for (entry = 0; entry < nentries; entry++) 232 { 233 values[m] = ...; 234 m++; 235 } 236 \endverbatim 237 **/ 238 HYPRE_Int HYPRE_StructMatrixSetBoxValues(HYPRE_StructMatrix matrix, 239 HYPRE_Int *ilower, 240 HYPRE_Int *iupper, 241 HYPRE_Int nentries, 242 HYPRE_Int *entries, 243 HYPRE_Complex *values); 244 /** 245 * Add to matrix coefficients a box at a time. The data in \e values is 246 * ordered as in \ref HYPRE_StructMatrixSetBoxValues. 247 **/ 248 HYPRE_Int HYPRE_StructMatrixAddToBoxValues(HYPRE_StructMatrix matrix, 249 HYPRE_Int *ilower, 250 HYPRE_Int *iupper, 251 HYPRE_Int nentries, 252 HYPRE_Int *entries, 253 HYPRE_Complex *values); 254 255 /** 256 * Set matrix coefficients a box at a time. The \e values array is logically 257 * box shaped with value-box extents \e vilower and \e viupper that must 258 * contain the set-box extents \e ilower and \e iupper . The data in the 259 * \e values array is ordered as in \ref HYPRE_StructMatrixSetBoxValues, but 260 * based on the value-box extents. 261 **/ 262 HYPRE_Int HYPRE_StructMatrixSetBoxValues2(HYPRE_StructMatrix matrix, 263 HYPRE_Int *ilower, 264 HYPRE_Int *iupper, 265 HYPRE_Int nentries, 266 HYPRE_Int *entries, 267 HYPRE_Int *vilower, 268 HYPRE_Int *viupper, 269 HYPRE_Complex *values); 270 /** 271 * Add to matrix coefficients a box at a time. The data in \e values is 272 * ordered as in \ref HYPRE_StructMatrixSetBoxValues2. 273 **/ 274 HYPRE_Int HYPRE_StructMatrixAddToBoxValues2(HYPRE_StructMatrix matrix, 275 HYPRE_Int *ilower, 276 HYPRE_Int *iupper, 277 HYPRE_Int nentries, 278 HYPRE_Int *entries, 279 HYPRE_Int *vilower, 280 HYPRE_Int *viupper, 281 HYPRE_Complex *values); 282 283 /** 284 * Finalize the construction of the matrix before using. 285 **/ 286 HYPRE_Int HYPRE_StructMatrixAssemble(HYPRE_StructMatrix matrix); 287 288 /** 289 * Get matrix coefficients index by index. The \e values array is of length 290 * \e nentries. 291 * 292 * NOTE: For better efficiency, use \ref HYPRE_StructMatrixGetBoxValues to get 293 * coefficients a box at a time. 294 **/ 295 HYPRE_Int HYPRE_StructMatrixGetValues(HYPRE_StructMatrix matrix, 296 HYPRE_Int *index, 297 HYPRE_Int nentries, 298 HYPRE_Int *entries, 299 HYPRE_Complex *values); 300 301 /** 302 * Get matrix coefficients a box at a time. The data in \e values is 303 * ordered as in \ref HYPRE_StructMatrixSetBoxValues. 304 **/ 305 HYPRE_Int HYPRE_StructMatrixGetBoxValues(HYPRE_StructMatrix matrix, 306 HYPRE_Int *ilower, 307 HYPRE_Int *iupper, 308 HYPRE_Int nentries, 309 HYPRE_Int *entries, 310 HYPRE_Complex *values); 311 312 /** 313 * Get matrix coefficients a box at a time. The data in \e values is 314 * ordered as in \ref HYPRE_StructMatrixSetBoxValues2. 315 **/ 316 HYPRE_Int HYPRE_StructMatrixGetBoxValues2(HYPRE_StructMatrix matrix, 317 HYPRE_Int *ilower, 318 HYPRE_Int *iupper, 319 HYPRE_Int nentries, 320 HYPRE_Int *entries, 321 HYPRE_Int *vilower, 322 HYPRE_Int *viupper, 323 HYPRE_Complex *values); 324 325 /** 326 * Define symmetry properties of the matrix. By default, matrices are assumed 327 * to be nonsymmetric. Significant storage savings can be made if the matrix is 328 * symmetric. 329 **/ 330 HYPRE_Int HYPRE_StructMatrixSetSymmetric(HYPRE_StructMatrix matrix, 331 HYPRE_Int symmetric); 332 333 /** 334 * Specify which stencil entries are constant over the grid. Declaring entries 335 * to be "constant over the grid" yields significant memory savings because 336 * the value for each declared entry will only be stored once. However, not all 337 * solvers are able to utilize this feature. 338 * 339 * Presently supported: 340 * - no entries constant (this function need not be called) 341 * - all entries constant 342 * - all but the diagonal entry constant 343 **/ 344 HYPRE_Int HYPRE_StructMatrixSetConstantEntries( HYPRE_StructMatrix matrix, 345 HYPRE_Int nentries, 346 HYPRE_Int *entries ); 347 348 /** 349 * Set the ghost layer in the matrix 350 **/ 351 HYPRE_Int HYPRE_StructMatrixSetNumGhost(HYPRE_StructMatrix matrix, 352 HYPRE_Int *num_ghost); 353 354 355 /** 356 * Print the matrix to file. This is mainly for debugging purposes. 357 **/ 358 HYPRE_Int HYPRE_StructMatrixPrint(const char *filename, 359 HYPRE_StructMatrix matrix, 360 HYPRE_Int all); 361 362 /** 363 * Matvec operator. This operation is \f$y = \alpha A x + \beta y\f$ . 364 * Note that you can do a simple matrix-vector multiply by setting 365 * \f$\alpha=1\f$ and \f$\beta=0\f$. 366 **/ 367 HYPRE_Int HYPRE_StructMatrixMatvec ( HYPRE_Complex alpha, 368 HYPRE_StructMatrix A, 369 HYPRE_StructVector x, 370 HYPRE_Complex beta, 371 HYPRE_StructVector y ); 372 373 /**@}*/ 374 375 /*-------------------------------------------------------------------------- 376 *--------------------------------------------------------------------------*/ 377 378 /** 379 * @name Struct Vectors 380 * 381 * @{ 382 **/ 383 384 struct hypre_StructVector_struct; 385 /** 386 * The vector object. 387 **/ 388 #ifndef HYPRE_StructVector_defined 389 typedef struct hypre_StructVector_struct *HYPRE_StructVector; 390 #endif 391 392 /** 393 * Create a vector object. 394 **/ 395 HYPRE_Int HYPRE_StructVectorCreate(MPI_Comm comm, 396 HYPRE_StructGrid grid, 397 HYPRE_StructVector *vector); 398 399 /** 400 * Destroy a vector object. 401 **/ 402 HYPRE_Int HYPRE_StructVectorDestroy(HYPRE_StructVector vector); 403 404 /** 405 * Prepare a vector object for setting coefficient values. 406 **/ 407 HYPRE_Int HYPRE_StructVectorInitialize(HYPRE_StructVector vector); 408 409 /** 410 * Set vector coefficients index by index. 411 * 412 * NOTE: For better efficiency, use \ref HYPRE_StructVectorSetBoxValues to set 413 * coefficients a box at a time. 414 **/ 415 HYPRE_Int HYPRE_StructVectorSetValues(HYPRE_StructVector vector, 416 HYPRE_Int *index, 417 HYPRE_Complex value); 418 419 /** 420 * Add to vector coefficients index by index. 421 * 422 * NOTE: For better efficiency, use \ref HYPRE_StructVectorAddToBoxValues to 423 * set coefficients a box at a time. 424 **/ 425 HYPRE_Int HYPRE_StructVectorAddToValues(HYPRE_StructVector vector, 426 HYPRE_Int *index, 427 HYPRE_Complex value); 428 429 /** 430 * Set vector coefficients a box at a time. The data in \e values is ordered 431 * as follows: 432 * 433 \verbatim 434 m = 0; 435 for (k = ilower[2]; k <= iupper[2]; k++) 436 for (j = ilower[1]; j <= iupper[1]; j++) 437 for (i = ilower[0]; i <= iupper[0]; i++) 438 { 439 values[m] = ...; 440 m++; 441 } 442 \endverbatim 443 **/ 444 HYPRE_Int HYPRE_StructVectorSetBoxValues(HYPRE_StructVector vector, 445 HYPRE_Int *ilower, 446 HYPRE_Int *iupper, 447 HYPRE_Complex *values); 448 /** 449 * Add to vector coefficients a box at a time. The data in \e values is 450 * ordered as in \ref HYPRE_StructVectorSetBoxValues. 451 **/ 452 HYPRE_Int HYPRE_StructVectorAddToBoxValues(HYPRE_StructVector vector, 453 HYPRE_Int *ilower, 454 HYPRE_Int *iupper, 455 HYPRE_Complex *values); 456 457 /** 458 * Set vector coefficients a box at a time. The \e values array is logically 459 * box shaped with value-box extents \e vilower and \e viupper that must 460 * contain the set-box extents \e ilower and \e iupper . The data in the 461 * \e values array is ordered as in \ref HYPRE_StructVectorSetBoxValues, but 462 * based on the value-box extents. 463 **/ 464 HYPRE_Int HYPRE_StructVectorSetBoxValues2(HYPRE_StructVector vector, 465 HYPRE_Int *ilower, 466 HYPRE_Int *iupper, 467 HYPRE_Int *vilower, 468 HYPRE_Int *viupper, 469 HYPRE_Complex *values); 470 /** 471 * Add to vector coefficients a box at a time. The data in \e values is 472 * ordered as in \ref HYPRE_StructVectorSetBoxValues2. 473 **/ 474 HYPRE_Int HYPRE_StructVectorAddToBoxValues2(HYPRE_StructVector vector, 475 HYPRE_Int *ilower, 476 HYPRE_Int *iupper, 477 HYPRE_Int *vilower, 478 HYPRE_Int *viupper, 479 HYPRE_Complex *values); 480 481 /** 482 * Finalize the construction of the vector before using. 483 **/ 484 HYPRE_Int HYPRE_StructVectorAssemble(HYPRE_StructVector vector); 485 486 /** 487 * Get vector coefficients index by index. 488 * 489 * NOTE: For better efficiency, use \ref HYPRE_StructVectorGetBoxValues to get 490 * coefficients a box at a time. 491 **/ 492 HYPRE_Int HYPRE_StructVectorGetValues(HYPRE_StructVector vector, 493 HYPRE_Int *index, 494 HYPRE_Complex *value); 495 496 /** 497 * Get vector coefficients a box at a time. The data in \e values is ordered 498 * as in \ref HYPRE_StructVectorSetBoxValues. 499 **/ 500 HYPRE_Int HYPRE_StructVectorGetBoxValues(HYPRE_StructVector vector, 501 HYPRE_Int *ilower, 502 HYPRE_Int *iupper, 503 HYPRE_Complex *values); 504 505 /** 506 * Get vector coefficients a box at a time. The data in \e values is ordered 507 * as in \ref HYPRE_StructVectorSetBoxValues2. 508 **/ 509 HYPRE_Int HYPRE_StructVectorGetBoxValues2(HYPRE_StructVector vector, 510 HYPRE_Int *ilower, 511 HYPRE_Int *iupper, 512 HYPRE_Int *vilower, 513 HYPRE_Int *viupper, 514 HYPRE_Complex *values); 515 516 /** 517 * Print the vector to file. This is mainly for debugging purposes. 518 **/ 519 HYPRE_Int HYPRE_StructVectorPrint(const char *filename, 520 HYPRE_StructVector vector, 521 HYPRE_Int all); 522 523 /**@}*/ 524 /**@}*/ 525 526 /*-------------------------------------------------------------------------- 527 * Miscellaneous: These probably do not belong in the interface. 528 *--------------------------------------------------------------------------*/ 529 530 HYPRE_Int HYPRE_StructMatrixGetGrid(HYPRE_StructMatrix matrix, 531 HYPRE_StructGrid *grid); 532 533 struct hypre_CommPkg_struct; 534 typedef struct hypre_CommPkg_struct *HYPRE_CommPkg; 535 536 HYPRE_Int HYPRE_StructVectorSetNumGhost(HYPRE_StructVector vector, 537 HYPRE_Int *num_ghost); 538 539 HYPRE_Int HYPRE_StructVectorSetConstantValues(HYPRE_StructVector vector, 540 HYPRE_Complex values); 541 542 HYPRE_Int HYPRE_StructVectorGetMigrateCommPkg(HYPRE_StructVector from_vector, 543 HYPRE_StructVector to_vector, 544 HYPRE_CommPkg *comm_pkg); 545 546 HYPRE_Int HYPRE_StructVectorMigrate(HYPRE_CommPkg comm_pkg, 547 HYPRE_StructVector from_vector, 548 HYPRE_StructVector to_vector); 549 550 HYPRE_Int HYPRE_CommPkgDestroy(HYPRE_CommPkg comm_pkg); 551 552 /*-------------------------------------------------------------------------- 553 *--------------------------------------------------------------------------*/ 554 555 #if 0 //defined(HYPRE_USING_CUDA) || defined(HYPRE_USING_HIP) 556 HYPRE_Int 557 HYPRE_StructGridSetDataLocation( HYPRE_StructGrid grid, HYPRE_MemoryLocation data_location ); 558 #endif 559 560 #ifdef __cplusplus 561 } 562 #endif 563 564 #endif 565 566