| 1 | /*BHEADER**********************************************************************
|
|---|
| 2 | * Copyright (c) 2008, Lawrence Livermore National Security, LLC.
|
|---|
| 3 | * Produced at the Lawrence Livermore National Laboratory.
|
|---|
| 4 | * This file is part of HYPRE. See file COPYRIGHT for details.
|
|---|
| 5 | *
|
|---|
| 6 | * HYPRE is free software; you can redistribute it and/or modify it under the
|
|---|
| 7 | * terms of the GNU Lesser General Public License (as published by the Free
|
|---|
| 8 | * Software Foundation) version 2.1 dated February 1999.
|
|---|
| 9 | *
|
|---|
| 10 | * $Revision: 2.4 $
|
|---|
| 11 | ***********************************************************************EHEADER*/
|
|---|
| 12 |
|
|---|
| 13 |
|
|---|
| 14 |
|
|---|
| 15 |
|
|---|
| 16 | #ifndef HYPRE_SSTRUCT_MV_HEADER
|
|---|
| 17 | #define HYPRE_SSTRUCT_MV_HEADER
|
|---|
| 18 |
|
|---|
| 19 | #include "HYPRE_utilities.h"
|
|---|
| 20 | #include "HYPRE.h"
|
|---|
| 21 | #include "HYPRE_struct_mv.h"
|
|---|
| 22 | #include "HYPRE_IJ_mv.h"
|
|---|
| 23 |
|
|---|
| 24 | #ifdef __cplusplus
|
|---|
| 25 | extern "C" {
|
|---|
| 26 | #endif
|
|---|
| 27 |
|
|---|
| 28 | /*--------------------------------------------------------------------------
|
|---|
| 29 | *--------------------------------------------------------------------------*/
|
|---|
| 30 |
|
|---|
| 31 | /**
|
|---|
| 32 | * @name SStruct System Interface
|
|---|
| 33 | *
|
|---|
| 34 | * This interface represents a semi-structured-grid conceptual view of a linear
|
|---|
| 35 | * system.
|
|---|
| 36 | *
|
|---|
| 37 | * @memo A semi-structured-grid conceptual interface
|
|---|
| 38 | **/
|
|---|
| 39 | /*@{*/
|
|---|
| 40 |
|
|---|
| 41 | /*--------------------------------------------------------------------------
|
|---|
| 42 | *--------------------------------------------------------------------------*/
|
|---|
| 43 |
|
|---|
| 44 | /**
|
|---|
| 45 | * @name SStruct Grids
|
|---|
| 46 | **/
|
|---|
| 47 | /*@{*/
|
|---|
| 48 |
|
|---|
| 49 | struct hypre_SStructGrid_struct;
|
|---|
| 50 | /**
|
|---|
| 51 | * A grid object is constructed out of several structured ``parts'' and an
|
|---|
| 52 | * optional unstructured ``part''. Each structured part has its own abstract
|
|---|
| 53 | * index space.
|
|---|
| 54 | **/
|
|---|
| 55 | typedef struct hypre_SStructGrid_struct *HYPRE_SStructGrid;
|
|---|
| 56 |
|
|---|
| 57 | enum hypre_SStructVariable_enum
|
|---|
| 58 | {
|
|---|
| 59 | HYPRE_SSTRUCT_VARIABLE_UNDEFINED = -1,
|
|---|
| 60 | HYPRE_SSTRUCT_VARIABLE_CELL = 0,
|
|---|
| 61 | HYPRE_SSTRUCT_VARIABLE_NODE = 1,
|
|---|
| 62 | HYPRE_SSTRUCT_VARIABLE_XFACE = 2,
|
|---|
| 63 | HYPRE_SSTRUCT_VARIABLE_YFACE = 3,
|
|---|
| 64 | HYPRE_SSTRUCT_VARIABLE_ZFACE = 4,
|
|---|
| 65 | HYPRE_SSTRUCT_VARIABLE_XEDGE = 5,
|
|---|
| 66 | HYPRE_SSTRUCT_VARIABLE_YEDGE = 6,
|
|---|
| 67 | HYPRE_SSTRUCT_VARIABLE_ZEDGE = 7
|
|---|
| 68 | };
|
|---|
| 69 | /**
|
|---|
| 70 | * An enumerated type that supports cell centered, node centered, face centered,
|
|---|
| 71 | * and edge centered variables. Face centered variables are split into x-face,
|
|---|
| 72 | * y-face, and z-face variables, and edge centered variables are split into
|
|---|
| 73 | * x-edge, y-edge, and z-edge variables. The edge centered variable types are
|
|---|
| 74 | * only used in 3D. In 2D, edge centered variables are handled by the face
|
|---|
| 75 | * centered types.
|
|---|
| 76 | *
|
|---|
| 77 | * Variables are referenced relative to an abstract (cell centered) index in the
|
|---|
| 78 | * following way:
|
|---|
| 79 | * \begin{itemize}
|
|---|
| 80 | * \item cell centered variables are aligned with the index;
|
|---|
| 81 | * \item node centered variables are aligned with the cell corner
|
|---|
| 82 | * at relative index (1/2, 1/2, 1/2);
|
|---|
| 83 | * \item x-face, y-face, and z-face centered variables are aligned
|
|---|
| 84 | * with the faces at relative indexes (1/2, 0, 0), (0, 1/2, 0),
|
|---|
| 85 | * and (0, 0, 1/2), respectively;
|
|---|
| 86 | * \item x-edge, y-edge, and z-edge centered variables are aligned
|
|---|
| 87 | * with the edges at relative indexes (0, 1/2, 1/2), (1/2, 0, 1/2),
|
|---|
| 88 | * and (1/2, 1/2, 0), respectively.
|
|---|
| 89 | * \end{itemize}
|
|---|
| 90 | *
|
|---|
| 91 | * The supported identifiers are:
|
|---|
| 92 | * \begin{itemize}
|
|---|
| 93 | * \item {\tt HYPRE\_SSTRUCT\_VARIABLE\_CELL}
|
|---|
| 94 | * \item {\tt HYPRE\_SSTRUCT\_VARIABLE\_NODE}
|
|---|
| 95 | * \item {\tt HYPRE\_SSTRUCT\_VARIABLE\_XFACE}
|
|---|
| 96 | * \item {\tt HYPRE\_SSTRUCT\_VARIABLE\_YFACE}
|
|---|
| 97 | * \item {\tt HYPRE\_SSTRUCT\_VARIABLE\_ZFACE}
|
|---|
| 98 | * \item {\tt HYPRE\_SSTRUCT\_VARIABLE\_XEDGE}
|
|---|
| 99 | * \item {\tt HYPRE\_SSTRUCT\_VARIABLE\_YEDGE}
|
|---|
| 100 | * \item {\tt HYPRE\_SSTRUCT\_VARIABLE\_ZEDGE}
|
|---|
| 101 | * \end{itemize}
|
|---|
| 102 | *
|
|---|
| 103 | * NOTE: Although variables are referenced relative to a unique abstract
|
|---|
| 104 | * cell-centered index, some variables are associated with multiple grid cells.
|
|---|
| 105 | * For example, node centered variables in 3D are associated with 8 cells (away
|
|---|
| 106 | * from boundaries). Although grid cells are distributed uniquely to different
|
|---|
| 107 | * processes, variables may be owned by multiple processes because they may be
|
|---|
| 108 | * associated with multiple cells.
|
|---|
| 109 | **/
|
|---|
| 110 | typedef enum hypre_SStructVariable_enum HYPRE_SStructVariable;
|
|---|
| 111 |
|
|---|
| 112 | /**
|
|---|
| 113 | * Create an {\tt ndim}-dimensional grid object with {\tt nparts} structured
|
|---|
| 114 | * parts.
|
|---|
| 115 | **/
|
|---|
| 116 | int HYPRE_SStructGridCreate(MPI_Comm comm,
|
|---|
| 117 | int ndim,
|
|---|
| 118 | int nparts,
|
|---|
| 119 | HYPRE_SStructGrid *grid);
|
|---|
| 120 |
|
|---|
| 121 | /**
|
|---|
| 122 | * Destroy a grid object. An object should be explicitly destroyed using this
|
|---|
| 123 | * destructor when the user's code no longer needs direct access to it. Once
|
|---|
| 124 | * destroyed, the object must not be referenced again. Note that the object may
|
|---|
| 125 | * not be deallocated at the completion of this call, since there may be
|
|---|
| 126 | * internal package references to the object. The object will then be destroyed
|
|---|
| 127 | * when all internal reference counts go to zero.
|
|---|
| 128 | **/
|
|---|
| 129 | int HYPRE_SStructGridDestroy(HYPRE_SStructGrid grid);
|
|---|
| 130 |
|
|---|
| 131 | /**
|
|---|
| 132 | * Set the extents for a box on a structured part of the grid.
|
|---|
| 133 | **/
|
|---|
| 134 | int HYPRE_SStructGridSetExtents(HYPRE_SStructGrid grid,
|
|---|
| 135 | int part,
|
|---|
| 136 | int *ilower,
|
|---|
| 137 | int *iupper);
|
|---|
| 138 |
|
|---|
| 139 | /**
|
|---|
| 140 | * Describe the variables that live on a structured part of the grid.
|
|---|
| 141 | **/
|
|---|
| 142 | int HYPRE_SStructGridSetVariables(HYPRE_SStructGrid grid,
|
|---|
| 143 | int part,
|
|---|
| 144 | int nvars,
|
|---|
| 145 | HYPRE_SStructVariable *vartypes);
|
|---|
| 146 |
|
|---|
| 147 | /**
|
|---|
| 148 | * Describe additional variables that live at a particular index. These
|
|---|
| 149 | * variables are appended to the array of variables set in
|
|---|
| 150 | * \Ref{HYPRE_SStructGridSetVariables}, and are referenced as such.
|
|---|
| 151 | **/
|
|---|
| 152 | int HYPRE_SStructGridAddVariables(HYPRE_SStructGrid grid,
|
|---|
| 153 | int part,
|
|---|
| 154 | int *index,
|
|---|
| 155 | int nvars,
|
|---|
| 156 | HYPRE_SStructVariable *vartypes);
|
|---|
| 157 |
|
|---|
| 158 | /**
|
|---|
| 159 | * Describe how regions just outside of a part relate to other parts. This is
|
|---|
| 160 | * done a box at a time.
|
|---|
| 161 | *
|
|---|
| 162 | * The indexes {\tt ilower} and {\tt iupper} map directly to the indexes {\tt
|
|---|
| 163 | * nbor\_ilower} and {\tt nbor\_iupper}. Although, it is required that indexes
|
|---|
| 164 | * increase from {\tt ilower} to {\tt iupper}, indexes may increase and/or
|
|---|
| 165 | * decrease from {\tt nbor\_ilower} to {\tt nbor\_iupper}.
|
|---|
| 166 | *
|
|---|
| 167 | * The {\tt index\_map} describes the mapping of indexes 0, 1, and 2 on part
|
|---|
| 168 | * {\tt part} to the corresponding indexes on part {\tt nbor\_part}. For
|
|---|
| 169 | * example, triple (1, 2, 0) means that indexes 0, 1, and 2 on part {\tt part}
|
|---|
| 170 | * map to indexes 1, 2, and 0 on part {\tt nbor\_part}, respectively.
|
|---|
| 171 | *
|
|---|
| 172 | * NOTE: All parts related to each other via this routine must have an identical
|
|---|
| 173 | * list of variables and variable types. For example, if part 0 has only two
|
|---|
| 174 | * variables on it, a cell centered variable and a node centered variable, and
|
|---|
| 175 | * we declare part 1 to be a neighbor of part 0, then part 1 must also have only
|
|---|
| 176 | * two variables on it, and they must be of type cell and node.
|
|---|
| 177 | **/
|
|---|
| 178 | int HYPRE_SStructGridSetNeighborBox(HYPRE_SStructGrid grid,
|
|---|
| 179 | int part,
|
|---|
| 180 | int *ilower,
|
|---|
| 181 | int *iupper,
|
|---|
| 182 | int nbor_part,
|
|---|
| 183 | int *nbor_ilower,
|
|---|
| 184 | int *nbor_iupper,
|
|---|
| 185 | int *index_map);
|
|---|
| 186 |
|
|---|
| 187 | /*
|
|---|
| 188 | * ** TEMPORARY routine until more thorough testing is completed **
|
|---|
| 189 | *
|
|---|
| 190 | * This is the same as HYPRE_SStructGridSetNeighborBox, except for the addition
|
|---|
| 191 | * of the last argument which enables hypre to couple a part to itself.
|
|---|
| 192 | *
|
|---|
| 193 | * SetNeighborBox calls can imply that certain variables on the grid are the
|
|---|
| 194 | * same as other variables on the grid. This redundancy must be reconciled
|
|---|
| 195 | * somehow. When SetNeighborBox couples the index spaces of two different
|
|---|
| 196 | * parts, hypre can resolve this redundancy issue very easily. However, when
|
|---|
| 197 | * SetNeighborBox couples the index space of a part to itself, resolving the
|
|---|
| 198 | * redundancey is much more complex and costly in general. The best solution to
|
|---|
| 199 | * this problem is to let the user dictate which variables are primary variables
|
|---|
| 200 | * and which are secondary variables.
|
|---|
| 201 | *
|
|---|
| 202 | * The last argument 'primary' works as follows:
|
|---|
| 203 | *
|
|---|
| 204 | * 'primary' > 0 - the 'part' box variables are primary variables
|
|---|
| 205 | * 'primary' = 0 - the 'part' box variables are secondary variables
|
|---|
| 206 | * 'primary' < 0 - let hypre decide; only works for two different parts
|
|---|
| 207 | *
|
|---|
| 208 | **/
|
|---|
| 209 | int HYPRE_SStructGridSetNeighborBoxZ(HYPRE_SStructGrid grid,
|
|---|
| 210 | int part,
|
|---|
| 211 | int *ilower,
|
|---|
| 212 | int *iupper,
|
|---|
| 213 | int nbor_part,
|
|---|
| 214 | int *nbor_ilower,
|
|---|
| 215 | int *nbor_iupper,
|
|---|
| 216 | int *index_map,
|
|---|
| 217 | int primary);
|
|---|
| 218 |
|
|---|
| 219 | /**
|
|---|
| 220 | * Add an unstructured part to the grid. The variables in the unstructured part
|
|---|
| 221 | * of the grid are referenced by a global rank between 0 and the total number of
|
|---|
| 222 | * unstructured variables minus one. Each process owns some unique consecutive
|
|---|
| 223 | * range of variables, defined by {\tt ilower} and {\tt iupper}.
|
|---|
| 224 | *
|
|---|
| 225 | * NOTE: This is just a placeholder. This part of the interface is not finished.
|
|---|
| 226 | **/
|
|---|
| 227 | int HYPRE_SStructGridAddUnstructuredPart(HYPRE_SStructGrid grid,
|
|---|
| 228 | int ilower,
|
|---|
| 229 | int iupper);
|
|---|
| 230 |
|
|---|
| 231 | /**
|
|---|
| 232 | * Finalize the construction of the grid before using.
|
|---|
| 233 | **/
|
|---|
| 234 | int HYPRE_SStructGridAssemble(HYPRE_SStructGrid grid);
|
|---|
| 235 |
|
|---|
| 236 | /**
|
|---|
| 237 | * Set periodic for a particular part.
|
|---|
| 238 | **/
|
|---|
| 239 | int HYPRE_SStructGridSetPeriodic(HYPRE_SStructGrid grid,
|
|---|
| 240 | int part,
|
|---|
| 241 | int *periodic);
|
|---|
| 242 | /**
|
|---|
| 243 | * Setting ghost in the sgrids.
|
|---|
| 244 | **/
|
|---|
| 245 | int HYPRE_SStructGridSetNumGhost(HYPRE_SStructGrid grid,
|
|---|
| 246 | int *num_ghost);
|
|---|
| 247 |
|
|---|
| 248 | /*@}*/
|
|---|
| 249 |
|
|---|
| 250 | /*--------------------------------------------------------------------------
|
|---|
| 251 | *--------------------------------------------------------------------------*/
|
|---|
| 252 |
|
|---|
| 253 | /**
|
|---|
| 254 | * @name SStruct Stencils
|
|---|
| 255 | **/
|
|---|
| 256 | /*@{*/
|
|---|
| 257 |
|
|---|
| 258 | struct hypre_SStructStencil_struct;
|
|---|
| 259 | /**
|
|---|
| 260 | * The stencil object.
|
|---|
| 261 | **/
|
|---|
| 262 | typedef struct hypre_SStructStencil_struct *HYPRE_SStructStencil;
|
|---|
| 263 |
|
|---|
| 264 | /**
|
|---|
| 265 | * Create a stencil object for the specified number of spatial dimensions and
|
|---|
| 266 | * stencil entries.
|
|---|
| 267 | **/
|
|---|
| 268 | int HYPRE_SStructStencilCreate(int ndim,
|
|---|
| 269 | int size,
|
|---|
| 270 | HYPRE_SStructStencil *stencil);
|
|---|
| 271 |
|
|---|
| 272 | /**
|
|---|
| 273 | * Destroy a stencil object.
|
|---|
| 274 | **/
|
|---|
| 275 | int HYPRE_SStructStencilDestroy(HYPRE_SStructStencil stencil);
|
|---|
| 276 |
|
|---|
| 277 | /**
|
|---|
| 278 | * Set a stencil entry.
|
|---|
| 279 | **/
|
|---|
| 280 | int HYPRE_SStructStencilSetEntry(HYPRE_SStructStencil stencil,
|
|---|
| 281 | int entry,
|
|---|
| 282 | int *offset,
|
|---|
| 283 | int var);
|
|---|
| 284 |
|
|---|
| 285 | /*@}*/
|
|---|
| 286 |
|
|---|
| 287 | /*--------------------------------------------------------------------------
|
|---|
| 288 | *--------------------------------------------------------------------------*/
|
|---|
| 289 |
|
|---|
| 290 | /**
|
|---|
| 291 | * @name SStruct Graphs
|
|---|
| 292 | **/
|
|---|
| 293 | /*@{*/
|
|---|
| 294 |
|
|---|
| 295 | struct hypre_SStructGraph_struct;
|
|---|
| 296 | /**
|
|---|
| 297 | * The graph object is used to describe the nonzero structure of a matrix.
|
|---|
| 298 | **/
|
|---|
| 299 | typedef struct hypre_SStructGraph_struct *HYPRE_SStructGraph;
|
|---|
| 300 |
|
|---|
| 301 | /**
|
|---|
| 302 | * Create a graph object.
|
|---|
| 303 | **/
|
|---|
| 304 | int HYPRE_SStructGraphCreate(MPI_Comm comm,
|
|---|
| 305 | HYPRE_SStructGrid grid,
|
|---|
| 306 | HYPRE_SStructGraph *graph);
|
|---|
| 307 |
|
|---|
| 308 | /**
|
|---|
| 309 | * Destroy a graph object.
|
|---|
| 310 | **/
|
|---|
| 311 | int HYPRE_SStructGraphDestroy(HYPRE_SStructGraph graph);
|
|---|
| 312 |
|
|---|
| 313 | /**
|
|---|
| 314 | * Set the stencil for a variable on a structured part of the grid.
|
|---|
| 315 | **/
|
|---|
| 316 | int HYPRE_SStructGraphSetStencil(HYPRE_SStructGraph graph,
|
|---|
| 317 | int part,
|
|---|
| 318 | int var,
|
|---|
| 319 | HYPRE_SStructStencil stencil);
|
|---|
| 320 |
|
|---|
| 321 | /**
|
|---|
| 322 | * Add a non-stencil graph entry at a particular index. This graph entry is
|
|---|
| 323 | * appended to the existing graph entries, and is referenced as such.
|
|---|
| 324 | *
|
|---|
| 325 | * NOTE: Users are required to set graph entries on all processes that own the
|
|---|
| 326 | * associated variables. This means that some data will be multiply defined.
|
|---|
| 327 | **/
|
|---|
| 328 | int HYPRE_SStructGraphAddEntries(HYPRE_SStructGraph graph,
|
|---|
| 329 | int part,
|
|---|
| 330 | int *index,
|
|---|
| 331 | int var,
|
|---|
| 332 | int to_part,
|
|---|
| 333 | int *to_index,
|
|---|
| 334 | int to_var);
|
|---|
| 335 |
|
|---|
| 336 | /**
|
|---|
| 337 | * Set the storage type of the associated matrix object. It is used before
|
|---|
| 338 | * AddEntries and Assemble to compute the right ranks in the graph.
|
|---|
| 339 | *
|
|---|
| 340 | * NOTE: This routine is only necessary for implementation reasons, and will
|
|---|
| 341 | * eventually be removed.
|
|---|
| 342 | *
|
|---|
| 343 | * @see HYPRE_SStructMatrixSetObjectType
|
|---|
| 344 | **/
|
|---|
| 345 | int HYPRE_SStructGraphSetObjectType(HYPRE_SStructGraph graph,
|
|---|
| 346 | int type);
|
|---|
| 347 | /**
|
|---|
| 348 | * Finalize the construction of the graph before using.
|
|---|
| 349 | **/
|
|---|
| 350 | int HYPRE_SStructGraphAssemble(HYPRE_SStructGraph graph);
|
|---|
| 351 |
|
|---|
| 352 | /*@}*/
|
|---|
| 353 |
|
|---|
| 354 | /*--------------------------------------------------------------------------
|
|---|
| 355 | *--------------------------------------------------------------------------*/
|
|---|
| 356 |
|
|---|
| 357 | /**
|
|---|
| 358 | * @name SStruct Matrices
|
|---|
| 359 | **/
|
|---|
| 360 | /*@{*/
|
|---|
| 361 |
|
|---|
| 362 | struct hypre_SStructMatrix_struct;
|
|---|
| 363 | /**
|
|---|
| 364 | * The matrix object.
|
|---|
| 365 | **/
|
|---|
| 366 | typedef struct hypre_SStructMatrix_struct *HYPRE_SStructMatrix;
|
|---|
| 367 |
|
|---|
| 368 | /**
|
|---|
| 369 | * Create a matrix object.
|
|---|
| 370 | **/
|
|---|
| 371 | int HYPRE_SStructMatrixCreate(MPI_Comm comm,
|
|---|
| 372 | HYPRE_SStructGraph graph,
|
|---|
| 373 | HYPRE_SStructMatrix *matrix);
|
|---|
| 374 |
|
|---|
| 375 | /**
|
|---|
| 376 | * Destroy a matrix object.
|
|---|
| 377 | **/
|
|---|
| 378 | int HYPRE_SStructMatrixDestroy(HYPRE_SStructMatrix matrix);
|
|---|
| 379 |
|
|---|
| 380 | /**
|
|---|
| 381 | * Prepare a matrix object for setting coefficient values.
|
|---|
| 382 | **/
|
|---|
| 383 | int HYPRE_SStructMatrixInitialize(HYPRE_SStructMatrix matrix);
|
|---|
| 384 |
|
|---|
| 385 | /**
|
|---|
| 386 | * Set matrix coefficients index by index. The {\tt values} array is of length
|
|---|
| 387 | * {\tt nentries}.
|
|---|
| 388 | *
|
|---|
| 389 | * NOTE: For better efficiency, use \Ref{HYPRE_SStructMatrixSetBoxValues} to set
|
|---|
| 390 | * coefficients a box at a time.
|
|---|
| 391 | *
|
|---|
| 392 | * NOTE: Users are required to set values on all processes that own the
|
|---|
| 393 | * associated variables. This means that some data will be multiply defined.
|
|---|
| 394 | *
|
|---|
| 395 | * NOTE: The entries in this routine must all be of the same type: either
|
|---|
| 396 | * stencil or non-stencil, but not both. Also, if they are stencil entries,
|
|---|
| 397 | * they must all represent couplings to the same variable type (there are no
|
|---|
| 398 | * such restrictions for non-stencil entries).
|
|---|
| 399 | *
|
|---|
| 400 | * If the matrix is complex, then {\tt values} consists of pairs of doubles
|
|---|
| 401 | * representing the real and imaginary parts of each complex value.
|
|---|
| 402 | *
|
|---|
| 403 | * @see HYPRE_SStructMatrixSetComplex
|
|---|
| 404 | **/
|
|---|
| 405 | int HYPRE_SStructMatrixSetValues(HYPRE_SStructMatrix matrix,
|
|---|
| 406 | int part,
|
|---|
| 407 | int *index,
|
|---|
| 408 | int var,
|
|---|
| 409 | int nentries,
|
|---|
| 410 | int *entries,
|
|---|
| 411 | double *values);
|
|---|
| 412 |
|
|---|
| 413 | /**
|
|---|
| 414 | * Add to matrix coefficients index by index. The {\tt values} array is of
|
|---|
| 415 | * length {\tt nentries}.
|
|---|
| 416 | *
|
|---|
| 417 | * NOTE: For better efficiency, use \Ref{HYPRE_SStructMatrixAddToBoxValues} to
|
|---|
| 418 | * set coefficients a box at a time.
|
|---|
| 419 | *
|
|---|
| 420 | * NOTE: Users are required to set values on all processes that own the
|
|---|
| 421 | * associated variables. This means that some data will be multiply defined.
|
|---|
| 422 | *
|
|---|
| 423 | * NOTE: The entries in this routine must all be of the same type: either
|
|---|
| 424 | * stencil or non-stencil, but not both. Also, if they are stencil entries,
|
|---|
| 425 | * they must all represent couplings to the same variable type.
|
|---|
| 426 | *
|
|---|
| 427 | * If the matrix is complex, then {\tt values} consists of pairs of doubles
|
|---|
| 428 | * representing the real and imaginary parts of each complex value.
|
|---|
| 429 | *
|
|---|
| 430 | * @see HYPRE_SStructMatrixSetComplex
|
|---|
| 431 | **/
|
|---|
| 432 | int HYPRE_SStructMatrixAddToValues(HYPRE_SStructMatrix matrix,
|
|---|
| 433 | int part,
|
|---|
| 434 | int *index,
|
|---|
| 435 | int var,
|
|---|
| 436 | int nentries,
|
|---|
| 437 | int *entries,
|
|---|
| 438 | double *values);
|
|---|
| 439 |
|
|---|
| 440 | /**
|
|---|
| 441 | * Set matrix coefficients a box at a time. The data in {\tt values} is ordered
|
|---|
| 442 | * as follows:
|
|---|
| 443 | *
|
|---|
| 444 | \begin{verbatim}
|
|---|
| 445 | m = 0;
|
|---|
| 446 | for (k = ilower[2]; k <= iupper[2]; k++)
|
|---|
| 447 | for (j = ilower[1]; j <= iupper[1]; j++)
|
|---|
| 448 | for (i = ilower[0]; i <= iupper[0]; i++)
|
|---|
| 449 | for (entry = 0; entry < nentries; entry++)
|
|---|
| 450 | {
|
|---|
| 451 | values[m] = ...;
|
|---|
| 452 | m++;
|
|---|
| 453 | }
|
|---|
| 454 | \end{verbatim}
|
|---|
| 455 | *
|
|---|
| 456 | * NOTE: Users are required to set values on all processes that own the
|
|---|
| 457 | * associated variables. This means that some data will be multiply defined.
|
|---|
| 458 | *
|
|---|
| 459 | * NOTE: The entries in this routine must all be of the same type: either
|
|---|
| 460 | * stencil or non-stencil, but not both. Also, if they are stencil entries,
|
|---|
| 461 | * they must all represent couplings to the same variable type (there are no
|
|---|
| 462 | * such restrictions for non-stencil entries).
|
|---|
| 463 | *
|
|---|
| 464 | * If the matrix is complex, then {\tt values} consists of pairs of doubles
|
|---|
| 465 | * representing the real and imaginary parts of each complex value.
|
|---|
| 466 | *
|
|---|
| 467 | * @see HYPRE_SStructMatrixSetComplex
|
|---|
| 468 | **/
|
|---|
| 469 | int HYPRE_SStructMatrixSetBoxValues(HYPRE_SStructMatrix matrix,
|
|---|
| 470 | int part,
|
|---|
| 471 | int *ilower,
|
|---|
| 472 | int *iupper,
|
|---|
| 473 | int var,
|
|---|
| 474 | int nentries,
|
|---|
| 475 | int *entries,
|
|---|
| 476 | double *values);
|
|---|
| 477 | /**
|
|---|
| 478 | * Add to matrix coefficients a box at a time. The data in {\tt values} is
|
|---|
| 479 | * ordered as in \Ref{HYPRE_SStructMatrixSetBoxValues}.
|
|---|
| 480 | *
|
|---|
| 481 | * NOTE: Users are required to set values on all processes that own the
|
|---|
| 482 | * associated variables. This means that some data will be multiply defined.
|
|---|
| 483 | *
|
|---|
| 484 | * NOTE: The entries in this routine must all be of stencil type. Also, they
|
|---|
| 485 | * must all represent couplings to the same variable type.
|
|---|
| 486 | *
|
|---|
| 487 | * If the matrix is complex, then {\tt values} consists of pairs of doubles
|
|---|
| 488 | * representing the real and imaginary parts of each complex value.
|
|---|
| 489 | *
|
|---|
| 490 | * @see HYPRE_SStructMatrixSetComplex
|
|---|
| 491 | **/
|
|---|
| 492 | int HYPRE_SStructMatrixAddToBoxValues(HYPRE_SStructMatrix matrix,
|
|---|
| 493 | int part,
|
|---|
| 494 | int *ilower,
|
|---|
| 495 | int *iupper,
|
|---|
| 496 | int var,
|
|---|
| 497 | int nentries,
|
|---|
| 498 | int *entries,
|
|---|
| 499 | double *values);
|
|---|
| 500 |
|
|---|
| 501 | /**
|
|---|
| 502 | * Finalize the construction of the matrix before using.
|
|---|
| 503 | **/
|
|---|
| 504 | int HYPRE_SStructMatrixAssemble(HYPRE_SStructMatrix matrix);
|
|---|
| 505 |
|
|---|
| 506 | /**
|
|---|
| 507 | * Define symmetry properties for the stencil entries in the matrix. The
|
|---|
| 508 | * boolean argument {\tt symmetric} is applied to stencil entries on part {\tt
|
|---|
| 509 | * part} that couple variable {\tt var} to variable {\tt to\_var}. A value of
|
|---|
| 510 | * -1 may be used for {\tt part}, {\tt var}, or {\tt to\_var} to specify
|
|---|
| 511 | * ``all''. For example, if {\tt part} and {\tt to\_var} are set to -1, then
|
|---|
| 512 | * the boolean is applied to stencil entries on all parts that couple variable
|
|---|
| 513 | * {\tt var} to all other variables.
|
|---|
| 514 | *
|
|---|
| 515 | * By default, matrices are assumed to be nonsymmetric. Significant
|
|---|
| 516 | * storage savings can be made if the matrix is symmetric.
|
|---|
| 517 | **/
|
|---|
| 518 | int HYPRE_SStructMatrixSetSymmetric(HYPRE_SStructMatrix matrix,
|
|---|
| 519 | int part,
|
|---|
| 520 | int var,
|
|---|
| 521 | int to_var,
|
|---|
| 522 | int symmetric);
|
|---|
| 523 |
|
|---|
| 524 | /**
|
|---|
| 525 | * Define symmetry properties for all non-stencil matrix entries.
|
|---|
| 526 | **/
|
|---|
| 527 | int HYPRE_SStructMatrixSetNSSymmetric(HYPRE_SStructMatrix matrix,
|
|---|
| 528 | int symmetric);
|
|---|
| 529 |
|
|---|
| 530 | /**
|
|---|
| 531 | * Set the storage type of the matrix object to be constructed. Currently, {\tt
|
|---|
| 532 | * type} can be either {\tt HYPRE\_SSTRUCT} (the default), {\tt HYPRE\_STRUCT},
|
|---|
| 533 | * or {\tt HYPRE\_PARCSR}.
|
|---|
| 534 | *
|
|---|
| 535 | * @see HYPRE_SStructMatrixGetObject
|
|---|
| 536 | **/
|
|---|
| 537 | int HYPRE_SStructMatrixSetObjectType(HYPRE_SStructMatrix matrix,
|
|---|
| 538 | int type);
|
|---|
| 539 |
|
|---|
| 540 | /**
|
|---|
| 541 | * Get a reference to the constructed matrix object.
|
|---|
| 542 | *
|
|---|
| 543 | * @see HYPRE_SStructMatrixSetObjectType
|
|---|
| 544 | **/
|
|---|
| 545 | int HYPRE_SStructMatrixGetObject(HYPRE_SStructMatrix matrix,
|
|---|
| 546 | void **object);
|
|---|
| 547 |
|
|---|
| 548 | /**
|
|---|
| 549 | * Set the matrix to be complex.
|
|---|
| 550 | **/
|
|---|
| 551 | int HYPRE_SStructMatrixSetComplex(HYPRE_SStructMatrix matrix);
|
|---|
| 552 |
|
|---|
| 553 | /**
|
|---|
| 554 | * Print the matrix to file. This is mainly for debugging purposes.
|
|---|
| 555 | **/
|
|---|
| 556 | int HYPRE_SStructMatrixPrint(const char *filename,
|
|---|
| 557 | HYPRE_SStructMatrix matrix,
|
|---|
| 558 | int all);
|
|---|
| 559 |
|
|---|
| 560 | /*@}*/
|
|---|
| 561 |
|
|---|
| 562 | /*--------------------------------------------------------------------------
|
|---|
| 563 | *--------------------------------------------------------------------------*/
|
|---|
| 564 |
|
|---|
| 565 | /**
|
|---|
| 566 | * @name SStruct Vectors
|
|---|
| 567 | **/
|
|---|
| 568 | /*@{*/
|
|---|
| 569 |
|
|---|
| 570 | struct hypre_SStructVector_struct;
|
|---|
| 571 | /**
|
|---|
| 572 | * The vector object.
|
|---|
| 573 | **/
|
|---|
| 574 | typedef struct hypre_SStructVector_struct *HYPRE_SStructVector;
|
|---|
| 575 |
|
|---|
| 576 | /**
|
|---|
| 577 | * Create a vector object.
|
|---|
| 578 | **/
|
|---|
| 579 | int HYPRE_SStructVectorCreate(MPI_Comm comm,
|
|---|
| 580 | HYPRE_SStructGrid grid,
|
|---|
| 581 | HYPRE_SStructVector *vector);
|
|---|
| 582 |
|
|---|
| 583 | /**
|
|---|
| 584 | * Destroy a vector object.
|
|---|
| 585 | **/
|
|---|
| 586 | int HYPRE_SStructVectorDestroy(HYPRE_SStructVector vector);
|
|---|
| 587 |
|
|---|
| 588 | /**
|
|---|
| 589 | * Prepare a vector object for setting coefficient values.
|
|---|
| 590 | **/
|
|---|
| 591 | int HYPRE_SStructVectorInitialize(HYPRE_SStructVector vector);
|
|---|
| 592 |
|
|---|
| 593 | /**
|
|---|
| 594 | * Set vector coefficients index by index.
|
|---|
| 595 | *
|
|---|
| 596 | * NOTE: For better efficiency, use \Ref{HYPRE_SStructVectorSetBoxValues} to set
|
|---|
| 597 | * coefficients a box at a time.
|
|---|
| 598 | *
|
|---|
| 599 | * NOTE: Users are required to set values on all processes that own the
|
|---|
| 600 | * associated variables. This means that some data will be multiply defined.
|
|---|
| 601 | *
|
|---|
| 602 | * If the vector is complex, then {\tt value} consists of a pair of doubles
|
|---|
| 603 | * representing the real and imaginary parts of the complex value.
|
|---|
| 604 | *
|
|---|
| 605 | * @see HYPRE_SStructVectorSetComplex
|
|---|
| 606 | **/
|
|---|
| 607 | int HYPRE_SStructVectorSetValues(HYPRE_SStructVector vector,
|
|---|
| 608 | int part,
|
|---|
| 609 | int *index,
|
|---|
| 610 | int var,
|
|---|
| 611 | double *value);
|
|---|
| 612 |
|
|---|
| 613 | /**
|
|---|
| 614 | * Add to vector coefficients index by index.
|
|---|
| 615 | *
|
|---|
| 616 | * NOTE: For better efficiency, use \Ref{HYPRE_SStructVectorAddToBoxValues} to
|
|---|
| 617 | * set coefficients a box at a time.
|
|---|
| 618 | *
|
|---|
| 619 | * NOTE: Users are required to set values on all processes that own the
|
|---|
| 620 | * associated variables. This means that some data will be multiply defined.
|
|---|
| 621 | *
|
|---|
| 622 | * If the vector is complex, then {\tt value} consists of a pair of doubles
|
|---|
| 623 | * representing the real and imaginary parts of the complex value.
|
|---|
| 624 | *
|
|---|
| 625 | * @see HYPRE_SStructVectorSetComplex
|
|---|
| 626 | **/
|
|---|
| 627 | int HYPRE_SStructVectorAddToValues(HYPRE_SStructVector vector,
|
|---|
| 628 | int part,
|
|---|
| 629 | int *index,
|
|---|
| 630 | int var,
|
|---|
| 631 | double *value);
|
|---|
| 632 |
|
|---|
| 633 | /**
|
|---|
| 634 | * Set vector coefficients a box at a time. The data in {\tt values} is ordered
|
|---|
| 635 | * as follows:
|
|---|
| 636 | *
|
|---|
| 637 | \begin{verbatim}
|
|---|
| 638 | m = 0;
|
|---|
| 639 | for (k = ilower[2]; k <= iupper[2]; k++)
|
|---|
| 640 | for (j = ilower[1]; j <= iupper[1]; j++)
|
|---|
| 641 | for (i = ilower[0]; i <= iupper[0]; i++)
|
|---|
| 642 | {
|
|---|
| 643 | values[m] = ...;
|
|---|
| 644 | m++;
|
|---|
| 645 | }
|
|---|
| 646 | \end{verbatim}
|
|---|
| 647 | *
|
|---|
| 648 | * NOTE: Users are required to set values on all processes that own the
|
|---|
| 649 | * associated variables. This means that some data will be multiply defined.
|
|---|
| 650 | *
|
|---|
| 651 | * If the vector is complex, then {\tt values} consists of pairs of doubles
|
|---|
| 652 | * representing the real and imaginary parts of each complex value.
|
|---|
| 653 | *
|
|---|
| 654 | * @see HYPRE_SStructVectorSetComplex
|
|---|
| 655 | **/
|
|---|
| 656 | int HYPRE_SStructVectorSetBoxValues(HYPRE_SStructVector vector,
|
|---|
| 657 | int part,
|
|---|
| 658 | int *ilower,
|
|---|
| 659 | int *iupper,
|
|---|
| 660 | int var,
|
|---|
| 661 | double *values);
|
|---|
| 662 | /**
|
|---|
| 663 | * Add to vector coefficients a box at a time. The data in {\tt values} is
|
|---|
| 664 | * ordered as in \Ref{HYPRE_SStructVectorSetBoxValues}.
|
|---|
| 665 | *
|
|---|
| 666 | * NOTE: Users are required to set values on all processes that own the
|
|---|
| 667 | * associated variables. This means that some data will be multiply defined.
|
|---|
| 668 | *
|
|---|
| 669 | * If the vector is complex, then {\tt values} consists of pairs of doubles
|
|---|
| 670 | * representing the real and imaginary parts of each complex value.
|
|---|
| 671 | *
|
|---|
| 672 | * @see HYPRE_SStructVectorSetComplex
|
|---|
| 673 | **/
|
|---|
| 674 | int HYPRE_SStructVectorAddToBoxValues(HYPRE_SStructVector vector,
|
|---|
| 675 | int part,
|
|---|
| 676 | int *ilower,
|
|---|
| 677 | int *iupper,
|
|---|
| 678 | int var,
|
|---|
| 679 | double *values);
|
|---|
| 680 |
|
|---|
| 681 | /**
|
|---|
| 682 | * Finalize the construction of the vector before using.
|
|---|
| 683 | **/
|
|---|
| 684 | int HYPRE_SStructVectorAssemble(HYPRE_SStructVector vector);
|
|---|
| 685 |
|
|---|
| 686 |
|
|---|
| 687 | /**
|
|---|
| 688 | * Gather vector data so that efficient {\tt GetValues} can be done. This
|
|---|
| 689 | * routine must be called prior to calling {\tt GetValues} to insure that
|
|---|
| 690 | * correct and consistent values are returned, especially for non cell-centered
|
|---|
| 691 | * data that is shared between more than one processor.
|
|---|
| 692 | **/
|
|---|
| 693 | int HYPRE_SStructVectorGather(HYPRE_SStructVector vector);
|
|---|
| 694 |
|
|---|
| 695 |
|
|---|
| 696 | /**
|
|---|
| 697 | * Get vector coefficients index by index.
|
|---|
| 698 | *
|
|---|
| 699 | * NOTE: For better efficiency, use \Ref{HYPRE_SStructVectorGetBoxValues} to get
|
|---|
| 700 | * coefficients a box at a time.
|
|---|
| 701 | *
|
|---|
| 702 | * NOTE: Users may only get values on processes that own the associated
|
|---|
| 703 | * variables.
|
|---|
| 704 | *
|
|---|
| 705 | * If the vector is complex, then {\tt value} consists of a pair of doubles
|
|---|
| 706 | * representing the real and imaginary parts of the complex value.
|
|---|
| 707 | *
|
|---|
| 708 | * @see HYPRE_SStructVectorSetComplex
|
|---|
| 709 | **/
|
|---|
| 710 | int HYPRE_SStructVectorGetValues(HYPRE_SStructVector vector,
|
|---|
| 711 | int part,
|
|---|
| 712 | int *index,
|
|---|
| 713 | int var,
|
|---|
| 714 | double *value);
|
|---|
| 715 |
|
|---|
| 716 | /**
|
|---|
| 717 | * Get vector coefficients a box at a time. The data in {\tt values} is ordered
|
|---|
| 718 | * as in \Ref{HYPRE_SStructVectorSetBoxValues}.
|
|---|
| 719 | *
|
|---|
| 720 | * NOTE: Users may only get values on processes that own the associated
|
|---|
| 721 | * variables.
|
|---|
| 722 | *
|
|---|
| 723 | * If the vector is complex, then {\tt values} consists of pairs of doubles
|
|---|
| 724 | * representing the real and imaginary parts of each complex value.
|
|---|
| 725 | *
|
|---|
| 726 | * @see HYPRE_SStructVectorSetComplex
|
|---|
| 727 | **/
|
|---|
| 728 | int HYPRE_SStructVectorGetBoxValues(HYPRE_SStructVector vector,
|
|---|
| 729 | int part,
|
|---|
| 730 | int *ilower,
|
|---|
| 731 | int *iupper,
|
|---|
| 732 | int var,
|
|---|
| 733 | double *values);
|
|---|
| 734 |
|
|---|
| 735 | /**
|
|---|
| 736 | * Set the storage type of the vector object to be constructed. Currently, {\tt
|
|---|
| 737 | * type} can be either {\tt HYPRE\_SSTRUCT} (the default), {\tt HYPRE\_STRUCT},
|
|---|
| 738 | * or {\tt HYPRE\_PARCSR}.
|
|---|
| 739 | *
|
|---|
| 740 | * @see HYPRE_SStructVectorGetObject
|
|---|
| 741 | **/
|
|---|
| 742 | int HYPRE_SStructVectorSetObjectType(HYPRE_SStructVector vector,
|
|---|
| 743 | int type);
|
|---|
| 744 |
|
|---|
| 745 | /**
|
|---|
| 746 | * Get a reference to the constructed vector object.
|
|---|
| 747 | *
|
|---|
| 748 | * @see HYPRE_SStructVectorSetObjectType
|
|---|
| 749 | **/
|
|---|
| 750 | int HYPRE_SStructVectorGetObject(HYPRE_SStructVector vector,
|
|---|
| 751 | void **object);
|
|---|
| 752 |
|
|---|
| 753 | /**
|
|---|
| 754 | * Set the vector to be complex.
|
|---|
| 755 | **/
|
|---|
| 756 | int HYPRE_SStructVectorSetComplex(HYPRE_SStructVector vector);
|
|---|
| 757 |
|
|---|
| 758 | /**
|
|---|
| 759 | * Print the vector to file. This is mainly for debugging purposes.
|
|---|
| 760 | **/
|
|---|
| 761 | int HYPRE_SStructVectorPrint(const char *filename,
|
|---|
| 762 | HYPRE_SStructVector vector,
|
|---|
| 763 | int all);
|
|---|
| 764 |
|
|---|
| 765 | /*@}*/
|
|---|
| 766 | /*@}*/
|
|---|
| 767 |
|
|---|
| 768 | /*--------------------------------------------------------------------------
|
|---|
| 769 | *--------------------------------------------------------------------------*/
|
|---|
| 770 |
|
|---|
| 771 | #ifdef __cplusplus
|
|---|
| 772 | }
|
|---|
| 773 | #endif
|
|---|
| 774 |
|
|---|
| 775 | #endif
|
|---|
| 776 |
|
|---|
