 |
Mesh Oriented datABase
(version 5.5.1)
An array-based unstructured mesh library
|
|
Mesh Oriented datABase
(version 5.5.1)
An array-based unstructured mesh library
|
1 #ifndef IMOAB_H
2 #define IMOAB_H
3 /**
4 * \file iMOAB.h
5 * iMOAB: a language-agnostic, lightweight interface to MOAB.
6 *
7 * Supports usage from C/C++, Fortran (77/90/2003), Python.
8 *
9 * \remark 1) All data in the interface are exposed via POD-types.
10 * \remark 2) Pass everything by reference, so we do not have to use %VAL()
11 * \remark 3) Arrays are allocated by the user code. No concerns about
12 * de-allocation of the data will be taken up by the interface.
13 * \remark 4) Always pass the pointer to the start of array along with the
14 * total allocated size for the array.
15 * \remark 5) Return the filled array requested by user along with
16 * optionally the actual length of the array that was filled.
17 * (for typical cases, should be the allocated length)
18 */
19
20 /**
21 * \Notes
22 * 1) Fortran MPI_Comm won't work. Take an integer argument and use MPI_F2C calls to get the C-Comm object
23 * 2) ReadHeaderInfo - Does it need the pid ?
24 * 3) Reuse the comm object from the registration for both load and write operations.
25 * Do not take comm objects again to avoid confusion and retain consistency.
26 * 4) Decipher the global comm object and the subset partioning for each application based on the comm object
27 * 5) GetMeshInfo - return separately the owned and ghosted vertices/elements -- not together in visible_** but rather
28 * owned_** and ghosted_**. Make these arrays of size 2.
29 * 6) Should we sort the vertices after ghosting, such that the locally owned is first, and the ghosted appended next.
30 * 7) RCM only for the owned part of the mesh -- do not screw with the ghosted layers
31 * 8) GetBlockID - identical to GetVertexID -- return the global numbering for block
32 * 9) GetVertexID -- remember that the order of vertices returned have an implicit numbering embedded in it.
33 * DO NOT CHANGE THIS ORDERING...
34 * 10) GetBlockInfo takes global Block ID; Remove blockname unless there is a separate use case for it..
35 * 11) GetElementConnectivity - clarify whether we return global or local vertex numbering.
36 * Preferably local numbering else lot of deciphering for global.
37 */
38 #include "moab/MOABConfig.h"
39 #include "moab/Types.hpp"
40
41 #ifdef __cplusplus
42 #include <cstdio>
43 #include <cassert>
44 #include <cstdlib>
45 #else
46 #include <stdio.h>
47 #include <assert.h>
48 #include <stdlib.h>
49 #endif
50
51 #define iMOAB_AppID int*
52 #define iMOAB_String char*
53 #define iMOAB_GlobalID int
54 #define iMOAB_LocalID int
55 #ifdef __cplusplus
56 #define ErrCode moab::ErrorCode
57 #else
58 #define ErrCode int
59 #endif
60
61 #ifdef _MSC_VER
62 #define __PRETTY_FUNCTION__ __FUNCSIG__
63 #else
64 #if !defined( __cplusplus ) || !defined( __PRETTY_FUNCTION__ )
65 #define __PRETTY_FUNCTION__ __func__
66 #endif
67 #endif
68
69 /**
70 * @brief MOAB tag types can be: dense/sparse, and of int/double/EntityHandle types.
71 * They can also be defined on both elements and vertices of the mesh.
72 */
73 enum MOAB_TAG_TYPE
74 {
75 DENSE_INTEGER = 0,
76 DENSE_DOUBLE = 1,
77 DENSE_ENTITYHANDLE = 2,
78 SPARSE_INTEGER = 3,
79 SPARSE_DOUBLE = 4,
80 SPARSE_ENTITYHANDLE = 5
81 };
82
83 /**
84 * @brief Define MOAB tag ownership information i.e., the entity where the tag is primarily defined
85 * This is typically used to query the tag data and to set it back.
86 */
87 enum MOAB_TAG_OWNER_TYPE
88 {
89 TAG_VERTEX = 0,
90 TAG_EDGE = 1,
91 TAG_FACE = 2,
92 TAG_ELEMENT = 3
93 };
94
95 #define CHK_MPI_ERR( ierr ) \
96 { \
97 if( 0 != ( ierr ) ) return moab::MB_FAILURE; \
98 }
99
100 #define IMOAB_CHECKPOINTER( prmObj, position ) \
101 { \
102 if( prmObj == nullptr ) \
103 { \
104 printf( "InputParamError at %d: '%s' is invalid and null.\n", position, #prmObj ); \
105 return moab::MB_UNHANDLED_OPTION; \
106 } \
107 }
108
109 #define IMOAB_THROW_ERROR( message, retval ) \
110 { \
111 printf( "iMOAB Error: %s.\n Location: %s in %s:%d.\n", message, __PRETTY_FUNCTION__, __FILE__, __LINE__ ); \
112 return retval; \
113 }
114
115 #ifndef NDEBUG
116 #define IMOAB_ASSERT_RET( condition, message, retval ) \
117 { \
118 if( !( condition ) ) \
119 { \
120 printf( "iMOAB Error: %s.\n Failed condition: %s\n Location: %s in %s:%d.\n", message, #condition, \
121 __PRETTY_FUNCTION__, __FILE__, __LINE__ ); \
122 return retval; \
123 } \
124 }
125
126 #define IMOAB_ASSERT( condition, message ) IMOAB_ASSERT_RET( condition, message, moab::MB_UNHANDLED_OPTION )
127
128 #else
129 #define IMOAB_ASSERT( condition, message )
130 #define IMOAB_ASSERT_RET( condition, message, retval )
131 #endif
132
133 #ifdef __cplusplus
134 extern "C" {
135 #endif
136
137 /**
138 * \brief Initialize the iMOAB interface implementation.
139 *
140 * \note Will create the MOAB instance, if not created already (reference counted).
141 *
142 * <B>Operations:</B> Collective
143 *
144 * \param[in] argc (int) Number of command line arguments
145 * \param[in] argv (iMOAB_String*) Command line arguments
146 * @return ErrCode
147 */
148 ErrCode iMOAB_Initialize( int argc, iMOAB_String* argv );
149
150 /**
151 * \brief Initialize the iMOAB interface implementation from Fortran driver.
152 *
153 * It will create the MOAB instance, if not created already (reference counted).
154 *
155 * <B>Operations:</B> Collective
156 *
157 * \return ErrCode The error code indicating success or failure.
158 */
159 ErrCode iMOAB_InitializeFortran( void );
160
161 /**
162 * \brief Finalize the iMOAB interface implementation.
163 *
164 * It will delete the internally reference counted MOAB instance, if the reference count reaches 0.
165 *
166 * <B>Operations:</B> Collective
167 *
168 * \return ErrCode The error code indicating success or failure.
169 */
170 ErrCode iMOAB_Finalize( void );
171
172 /**
173 * \brief Register application - Create a unique application ID and bootstrap interfaces for further queries.
174 *
175 * \note
176 * Internally, a mesh set will be associated with the application ID and all subsequent queries on the MOAB
177 * instance will be directed to this mesh/file set.
178 *
179 * <B>Operations:</B> Collective
180 *
181 * \param[in] app_name (iMOAB_String) Application name (PROTEUS, NEK5000, etc)
182 * \param[in] comm (MPI_Comm*) MPI communicator to be used for all mesh-related queries originating
183 * from this application
184 * \param[in] compid (int*) The unique external component identifier
185 * \param[out] pid (iMOAB_AppID) The unique pointer to the application ID
186 * \return ErrCode The error code indicating success or failure.
187 */
188 ErrCode iMOAB_RegisterApplication( const iMOAB_String app_name,
189 #ifdef MOAB_HAVE_MPI
190 MPI_Comm* comm,
191 #endif
192 int* compid,
193 iMOAB_AppID pid );
194
195 /**
196 * \brief De-Register application: delete mesh (set) associated with the application ID.
197 *
198 * \note The associated communicator will be released, and all associated mesh entities and sets will be deleted from the
199 * mesh data structure. Associated tag storage data will be freed too.
200 *
201 * <B>Operations:</B> Collective
202 *
203 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID
204 * \return ErrCode The error code indicating success or failure.
205 */
206 ErrCode iMOAB_DeregisterApplication( iMOAB_AppID pid );
207
208 /**
209 * \brief Register a Fortran-based application - Create a unique application ID and bootstrap interfaces
210 * for further queries.
211 *
212 * \note
213 * Internally, the comm object, usually a 32 bit integer in Fortran, will be converted using MPI_Comm_f2c and stored as
214 * MPI_Comm. A mesh set will be associated with the application ID and all subsequent queries on the MOAB instance will
215 * be directed to this mesh/file set.
216 *
217 * <B>Operations:</B> Collective
218 *
219 * \param[in] app_name (iMOAB_String) Application name ("MySolver", "E3SM", "DMMoab", "PROTEUS", "NEK5000", etc)
220 * \param[in] communicator (int*) Fortran MPI communicator to be used for all mesh-related queries originating from this application.
221 * \param[in] compid (int*) External component id, (A *const* unique identifier).
222 * \param[out] pid (iMOAB_AppID) The unique pointer to the application ID.
223 * \return ErrCode The error code indicating success or failure.
224 */
225 ErrCode iMOAB_RegisterApplicationFortran( const iMOAB_String app_name,
226 #ifdef MOAB_HAVE_MPI
227 int* communicator,
228 #endif
229 int* compid,
230 iMOAB_AppID pid );
231
232 /**
233 * \brief De-Register the Fortran based application: delete mesh (set) associated with the application ID.
234 *
235 * \note The associated communicator will be released, and all associated mesh entities and sets will be
236 * deleted from the mesh data structure. Associated tag storage data will be freed too.
237 *
238 * <B>Operations:</B> Collective
239 *
240 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID
241 * \return ErrCode The error code indicating success or failure.
242 */
243 ErrCode iMOAB_DeregisterApplicationFortran( iMOAB_AppID pid );
244
245 /**
246 * \brief It should be called on master task only, and information obtained could be broadcasted by the user.
247 * It is a fast lookup in the header of the file.
248 *
249 * \note
250 * <B>Operations:</B> Not collective
251 *
252 * \param[in] filename (iMOAB_String) The MOAB mesh file (H5M) to probe for header information.
253 * \param[out] num_global_vertices (int*) The total number of vertices in the mesh file.
254 * \param[out] num_global_elements (int*) The total number of elements (of highest dimension only).
255 * \param[out] num_dimension (int*) The highest dimension of elements in the mesh
256 * (Edge=1, Tri/Quad=2, Tet/Hex/Prism/Pyramid=3).
257 * \param[out] num_parts (int*) The total number of partitions available in the mesh file, typically
258 * partitioned with mbpart during pre-processing.
259 * \return ErrCode The error code indicating success or failure.
260 */
261 ErrCode iMOAB_ReadHeaderInfo( const iMOAB_String filename,
262 int* num_global_vertices,
263 int* num_global_elements,
264 int* num_dimension,
265 int* num_parts );
266
267 /**
268 * \brief Load a MOAB mesh file in parallel and exchange ghost layers as requested.
269 *
270 * \note All communication is MPI-based, and read options include parallel loading information, resolving
271 * shared entities. Local MOAB instance is populated with mesh cells and vertices in the corresponding
272 * local partitions.
273 *
274 * This will also exchange ghost cells and vertices, as requested. The default bridge dimension is 0 (vertices),
275 * and all additional lower dimensional sub-entities are exchanged (mesh edges and faces). The tags in the file are not
276 * exchanged by default. Default tag information for GLOBAL_ID, MATERIAL_SET, NEUMANN_SET and DIRICHLET_SET is
277 * exchanged. Global ID tag is exchanged for all cells and vertices. Material sets, Neumann sets and Dirichlet sets
278 * are all augmented with the ghost entities.
279 *
280 * <B>Operations:</B> Collective
281 *
282 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
283 * \param[in] filename (iMOAB_String) The MOAB mesh file (H5M) to load onto the internal application mesh set.
284 * \param[in] read_options (iMOAB_String) Additional options for reading the MOAB mesh file in parallel.
285 * \param[in] num_ghost_layers (int*) The total number of ghost layers to exchange during mesh loading.
286 * \return ErrCode The error code indicating success or failure.
287 */
288 ErrCode iMOAB_LoadMesh( iMOAB_AppID pid,
289 const iMOAB_String filename,
290 const iMOAB_String read_options,
291 int* num_ghost_layers );
292
293 /**
294 * \brief Create vertices for an app; it assumes no other vertices
295 *
296 * \note <B>Operations:</B> Not collective
297 *
298 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
299 * \param[in] coords_len (int*) Size of the \p coordinates array (nverts * dim).
300 * \param[in] dim (int*) Dimension of the vertex coordinates (usually 3).
301 * \param[in] coordinates (double*) Coordinates of all vertices, interleaved.
302 * \return ErrCode The error code indicating success or failure.
303 */
304 ErrCode iMOAB_CreateVertices( iMOAB_AppID pid, int* coords_len, int* dim, double* coordinates );
305
306 /**
307 * \brief Create elements for an app; it assumes connectivity from local vertices, in order
308 *
309 * \note <B>Operations:</B> Not collective
310 *
311 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
312 * \param[in] num_elem (int*) Number of elements.
313 * \param[in] type (int*) Type of element (moab type).
314 * \param[in] num_nodes_per_element (int*) Number of nodes per element.
315 * \param[in] connectivity (int *) Connectivity array, with respect to vertices (assumed contiguous).
316 * \param[in] block_ID (int *) The local block identifier, which will now contain the elements.
317 * \return ErrCode The error code indicating success or failure.
318 */
319 ErrCode iMOAB_CreateElements( iMOAB_AppID pid,
320 int* num_elem,
321 int* type,
322 int* num_nodes_per_element,
323 int* connectivity,
324 int* block_ID );
325
326 /**
327 * \brief Resolve shared entities using global markers on shared vertices.
328 *
329 * \note Global markers can be a global node id, for example, or a global DoF number (as for HOMME)
330 *
331 * <B>Operations:</B> Collective .
332 *
333 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
334 * \param[in] num_verts (int*) Number of vertices.
335 * \param[in] marker (int*) Resolving marker (global id marker).
336 * \return ErrCode The error code indicating success or failure.
337 */
338 ErrCode iMOAB_ResolveSharedEntities( iMOAB_AppID pid, int* num_verts, int* marker );
339
340 /**
341 * \brief Create the requested number of ghost layers for the parallel mesh.
342 *
343 * \note The routine assumes that the shared entities were resolved successfully, and that
344 * the mesh is properly distributed on separate tasks.
345 *
346 * <B>Operations:</B> Collective.
347 *
348 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
349 * \param[in] ghost_dim (int*) Desired ghost dimension (2 or 3, most of the time).
350 * \param[in] num_ghost_layers (int*) Number of ghost layers requested.
351 * \param[in] bridge_dim (int*) Bridge dimension (0 for vertices, 1 for edges, 2 for faces).
352 * \return ErrCode The error code indicating success or failure.
353 */
354 ErrCode iMOAB_DetermineGhostEntities( iMOAB_AppID pid, int* ghost_dim, int* num_ghost_layers, int* bridge_dim );
355
356 /**
357 * \brief Write a MOAB mesh along with the solution tags to a file.
358 *
359 * \note The interface will write one single file (H5M) and for serial files (VTK/Exodus), it will write one
360 * file per task. Write options include parallel write options, if needed. Only the mesh set and solution data
361 * associated to the application will be written to the file.
362 *
363 * <B>Operations:</B> Collective for parallel write, non collective for serial write.
364 *
365 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
366 * \param[in] filename (iMOAB_String) The MOAB mesh file (H5M) to write all the entities contained in the
367 * internal application mesh set.
368 * \param[in] write_options (iMOAB_String) Additional options for writing the MOAB mesh in parallel.
369 * \return ErrCode The error code indicating success or failure.
370 */
371 ErrCode iMOAB_WriteMesh( iMOAB_AppID pid, const iMOAB_String filename, const iMOAB_String write_options );
372
373 /**
374 * \brief Write a local MOAB mesh copy.
375 *
376 * \note The interface will write one file per task. Only the local mesh set and solution data associated
377 * to the application will be written to the file. Very convenient method used for debugging.
378 *
379 * <B>Operations:</B> Not Collective (independent operation).
380 *
381 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
382 * \param[in] prefix (iMOAB_String) The MOAB file prefix that will be used with task ID in parallel.
383 * \return ErrCode The error code indicating success or failure.
384 */
385 ErrCode iMOAB_WriteLocalMesh( iMOAB_AppID pid, iMOAB_String prefix );
386
387 /**
388 * \brief Update local mesh data structure, from file information.
389 *
390 * \note The method should be called after mesh modifications, for example reading a file or creating mesh in memory
391 *
392 * <B>Operations:</B> Collective
393 *
394 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
395 * \return ErrCode The error code indicating success or failure.
396 */
397 ErrCode iMOAB_UpdateMeshInfo( iMOAB_AppID pid );
398
399 /**
400 * \brief Retrieve all the important mesh information related to vertices, elements, vertex and surface boundary conditions.
401 *
402 * \note Number of visible vertices and cells include ghost entities. All arrays returned have size 3.
403 * Local entities are first, then ghost entities are next. Shared vertices can be owned in MOAB sense by
404 * different tasks. Ghost vertices and cells are always owned by other tasks.
405 *
406 * <B>Operations:</B> Not Collective
407 *
408 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
409 * \param[out] num_visible_vertices (int*) The number of vertices in the current partition/process arranged.
410 * as: owned/shared only, ghosted, total_visible (array allocated by
411 * user, <TT>size := 3</TT>).
412 * \param[out] num_visible_elements (int*) The number of elements in current partition/process arranged as: owned only,
413 * ghosted/shared, total_visible (array allocated by user, <TT>size := 3</TT>).
414 * \param[out] num_visible_blocks (int*) The number of material sets in local mesh in current partition/process
415 * arranged as: owned only, ghosted/shared, total_visible (array allocated by
416 * user, <TT>size := 3</TT>).
417 * \param[out] num_visible_surfaceBC (int*) The number of mesh surfaces that have a NEUMANN_SET BC defined in local mesh
418 * in current partition/process arranged as: owned only, ghosted/shared,
419 * total_visible (array allocated by user, <TT>size := 3</TT>).
420 * \param[out] num_visible_vertexBC (int*) The number of vertices that have a DIRICHLET_SET BC defined in local mesh in
421 * current partition/process arranged as: owned only, ghosted/shared,
422 * total_visible (array allocated by user, <TT>size := 3</TT>).
423 * \return ErrCode The error code indicating success or failure.
424 */
425 ErrCode iMOAB_GetMeshInfo( iMOAB_AppID pid,
426 int* num_visible_vertices,
427 int* num_visible_elements,
428 int* num_visible_blocks,
429 int* num_visible_surfaceBC,
430 int* num_visible_vertexBC );
431
432 /**
433 * \brief Get the global vertex IDs for all locally visible (owned and shared/ghosted) vertices.
434 *
435 * \note The array should be allocated by the user, sized with the total number of visible vertices
436 * from iMOAB_GetMeshInfo method.
437 *
438 * <B>Operations:</B> Not collective
439 *
440 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
441 * \param[in] vertices_length (int*) The allocated size of array
442 * (typical <TT>size := num_visible_vertices</TT>).
443 * \param[out] global_vertex_ID (iMOAB_GlobalID*) The global IDs for all locally visible
444 * vertices (array allocated by user).
445 * \return ErrCode The error code indicating success or failure.
446 */
447 ErrCode iMOAB_GetVertexID( iMOAB_AppID pid, int* vertices_length, iMOAB_GlobalID* global_vertex_ID );
448
449 /**
450 * \brief Get vertex ownership information.
451 *
452 * For each vertex based on the local ID, return the process that owns the vertex (local, shared or ghost)
453 *
454 * \note Shared vertices could be owned by different tasks. Local and shared vertices are first, ghost
455 * vertices are next in the array. Ghost vertices are always owned by a different process ID. Array allocated
456 * by the user with total size of visible vertices.
457 *
458 * <B>Operations:</B> Not Collective
459 *
460 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
461 * \param[in] vertices_length (int*) The allocated size of array
462 * (typically <TT>size := num_visible_vertices</TT>).
463 * \param[out] visible_global_rank_ID (int*) The processor rank owning each of the local vertices.
464 * \return ErrCode The error code indicating success or failure.
465 */
466 ErrCode iMOAB_GetVertexOwnership( iMOAB_AppID pid, int* vertices_length, int* visible_global_rank_ID );
467
468 /**
469 * \brief Get vertex coordinates for all local (owned and ghosted) vertices.
470 *
471 * \note coordinates are returned in an array allocated by user, interleaved. (do need an option for blocked
472 * coordinates ?) size of the array is dimension times number of visible vertices. The local ordering is implicit,
473 * owned/shared vertices are first, then ghosts.
474 *
475 * <B>Operations:</B> Not Collective
476 *
477 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
478 * \param[in] coords_length (int*) The size of the allocated coordinate array (array allocated by
479 * user, <TT>size := 3*num_visible_vertices</TT>).
480 * \param[out] coordinates (double*) The pointer to user allocated memory that will be filled with
481 * interleaved coordinates.
482 * \return ErrCode The error code indicating success or failure.
483 */
484 ErrCode iMOAB_GetVisibleVerticesCoordinates( iMOAB_AppID pid, int* coords_length, double* coordinates );
485
486 /**
487 * \brief Get the global block IDs for all locally visible (owned and shared/ghosted) blocks.
488 *
489 * \note Block IDs are corresponding to MATERIAL_SET tags for material sets. Usually the block ID is exported
490 * from Cubit as a unique integer value. First blocks are local, and next blocks are fully ghosted. First blocks
491 * have at least one owned cell/element, ghost blocks have only ghost cells. Internally, a block corresponds to a
492 * mesh set with a MATERIAL_SET tag value equal to the block ID.
493 *
494 * <B>Operations:</B> Not Collective
495 *
496 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
497 * \param[in] block_length (int*) The allocated size of array
498 * (typical <TT>size := num_visible_blocks</TT>).
499 * \param[out] global_block_IDs (iMOAB_GlobalID*) The global IDs for all locally visible blocks
500 * (array allocated by user).
501 * \return ErrCode The error code indicating success or failure.
502 */
503 ErrCode iMOAB_GetBlockID( iMOAB_AppID pid, int* block_length, iMOAB_GlobalID* global_block_IDs );
504
505 /**
506 * \brief Get the global block information and number of visible elements of belonging to a
507 * block (MATERIAL SET).
508 *
509 * \note A block has to be homogeneous, it can contain elements of a single type.
510 *
511 * <B>Operations:</B> Not Collective
512 *
513 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
514 * \param[in] global_block_ID (iMOAB_GlobalID) The global block ID of the set to be queried.
515 * \param[out] vertices_per_element (int*) The number of vertices per element.
516 * \param[out] num_elements_in_block (int*) The number of elements in block.
517 * \return ErrCode The error code indicating success or failure.
518 */
519 ErrCode iMOAB_GetBlockInfo( iMOAB_AppID pid,
520 iMOAB_GlobalID* global_block_ID,
521 int* vertices_per_element,
522 int* num_elements_in_block );
523
524 /**
525 * \brief Get the visible elements information.
526 *
527 * Return for all visible elements the global IDs, ranks they belong to, block ids they belong to.
528 *
529 * \todo : Can we also return the index for each block ID?
530 *
531 * \note <B>Operations:</B> Not Collective
532 *
533 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
534 * \param[in] num_visible_elements (int*) The number of visible elements (returned by \c GetMeshInfo).
535 * \param[out] element_global_IDs (iMOAB_GlobalID*) Element global ids to be added to the block.
536 * \param[out] ranks (int*) The owning ranks of elements.
537 * \param[out] block_IDs (iMOAB_GlobalID*) The block ids containing the elements.
538 * \return ErrCode The error code indicating success or failure.
539 */
540 ErrCode iMOAB_GetVisibleElementsInfo( iMOAB_AppID pid,
541 int* num_visible_elements,
542 iMOAB_GlobalID* element_global_IDs,
543 int* ranks,
544 iMOAB_GlobalID* block_IDs );
545
546 /**
547 * \brief Get the connectivities for elements contained within a certain block.
548 *
549 * \note input is the block ID. Should we change to visible block local index?
550 *
551 * <B>Operations:</B> Not Collective
552 *
553 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
554 * \param[in] global_block_ID (iMOAB_GlobalID*) The global block ID of the set being queried.
555 * \param[in] connectivity_length (int*) The allocated size of array.
556 * (typical <TT>size := vertices_per_element*num_elements_in_block</TT>)
557 * \param[out] element_connectivity (int*) The connectivity array to store element ordering in MOAB canonical
558 * numbering scheme (array allocated by user); array contains vertex
559 * indices in the local numbering order for vertices elements are in
560 * the same order as provided by GetElementOwnership and GetElementID.
561 * \return ErrCode The error code indicating success or failure.
562 */
563 ErrCode iMOAB_GetBlockElementConnectivities( iMOAB_AppID pid,
564 iMOAB_GlobalID* global_block_ID,
565 int* connectivity_length,
566 int* element_connectivity );
567
568 /**
569 * \brief Get the connectivity for one element only.
570 *
571 * \note This is a convenience method and in general should not be used unless necessary.
572 * You should use colaesced calls for multiple elements for efficiency.
573 *
574 * <B>Operations:</B> Not Collective
575 *
576 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
577 * \param[in] elem_index (iMOAB_LocalID *) Local element index.
578 * \param[in,out] connectivity_length (int *) On input, maximum length of connectivity. On output, actual length.
579 * \param[out] element_connectivity (int*) The connectivity array to store connectivity in MOAB canonical numbering
580 * scheme. Array contains vertex indices in the local numbering order for
581 * vertices.
582 * \return ErrCode The error code indicating success or failure.
583 */
584 ErrCode iMOAB_GetElementConnectivity( iMOAB_AppID pid,
585 iMOAB_LocalID* elem_index,
586 int* connectivity_length,
587 int* element_connectivity );
588
589 /**
590 * \brief Get the element ownership within a certain block i.e., processor ID of the element owner.
591 *
592 * \note : Should we use local block index for input, instead of the global block ID ?
593 *
594 * <B>Operations:</B> Not Collective
595 *
596 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
597 * \param[in] global_block_ID (iMOAB_GlobalID) The global block ID of the set being queried.
598 * \param[in] num_elements_in_block (int*) The allocated size of ownership array, same as
599 * <TT>num_elements_in_block</TT> returned from GetBlockInfo().
600 * \param[out] element_ownership (int*) The ownership array to store processor ID for all elements
601 * (array allocated by user).
602 * \return ErrCode The error code indicating success or failure.
603 */
604 ErrCode iMOAB_GetElementOwnership( iMOAB_AppID pid,
605 iMOAB_GlobalID* global_block_ID,
606 int* num_elements_in_block,
607 int* element_ownership );
608
609 /**
610 * \brief Get the global IDs for all locally visible elements belonging to a particular block.
611 *
612 * \note The method will return also the local index of each element, in the local range that contains
613 * all visible elements.
614 *
615 * <B>Operations:</B> Not Collective
616 *
617 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
618 * \param[in] global_block_ID (iMOAB_GlobalID*) The global block ID of the set being queried.
619 * \param[in] num_elements_in_block (int*) The allocated size of global element ID array, same as
620 * <TT>num_elements_in_block</TT> returned from GetBlockInfo().
621 * \param[out] global_element_ID (iMOAB_GlobalID*) The global IDs for all locally visible elements
622 * (array allocated by user).
623 * \param[out] local_element_ID (iMOAB_LocalID*) (<I><TT>Optional</TT></I>) The local IDs for all locally visible
624 * elements (index in the range of all primary elements in the rank)
625 * \return ErrCode The error code indicating success or failure.
626 */
627 ErrCode iMOAB_GetElementID( iMOAB_AppID pid,
628 iMOAB_GlobalID* global_block_ID,
629 int* num_elements_in_block,
630 iMOAB_GlobalID* global_element_ID,
631 iMOAB_LocalID* local_element_ID );
632
633 /**
634 * \brief Get the surface boundary condition information.
635 *
636 * \note <B>Operations:</B> Not Collective
637 *
638 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
639 * \param[in] surface_BC_length (int*) The allocated size of surface boundary condition array, same
640 * as <TT>num_visible_surfaceBC</TT> returned by GetMeshInfo().
641 * \param[out] local_element_ID (iMOAB_LocalID*) The local element IDs that contains the side with the surface BC.
642 * \param[out] reference_surface_ID (int*) The surface number with the BC in the canonical reference
643 * element (e.g., 1 to 6 for HEX, 1-4 for TET).
644 * \param[out] boundary_condition_value (int*) The boundary condition type as obtained from the mesh description
645 * (value of the NeumannSet defined on the element).
646 * \return ErrCode The error code indicating success or failure.
647 */
648 ErrCode iMOAB_GetPointerToSurfaceBC( iMOAB_AppID pid,
649 int* surface_BC_length,
650 iMOAB_LocalID* local_element_ID,
651 int* reference_surface_ID,
652 int* boundary_condition_value );
653
654 /**
655 * \brief Get the vertex boundary condition information.
656 *
657 * \note <B>Operations:</B> Not Collective
658 *
659 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
660 * \param[in] vertex_BC_length (int) The allocated size of vertex boundary condition array, same as
661 * <TT>num_visible_vertexBC</TT> returned by GetMeshInfo().
662 * \param[out] local_vertex_ID (iMOAB_LocalID*) The local vertex ID that has Dirichlet BC defined.
663 * \param[out] boundary_condition_value (int*) The boundary condition type as obtained from the mesh description
664 * (value of the Dirichlet_Set tag defined on the vertex).
665 * \return ErrCode The error code indicating success or failure.
666 */
667 ErrCode iMOAB_GetPointerToVertexBC( iMOAB_AppID pid,
668 int* vertex_BC_length,
669 iMOAB_LocalID* local_vertex_ID,
670 int* boundary_condition_value );
671
672 /**
673 * \brief Define a MOAB Tag corresponding to the application depending on requested types.
674 *
675 * \note In MOAB, for most solution vectors, we only need to create a "Dense", "Double" Tag. A sparse tag can
676 * be created too. If the tag is already existing in the file, it will not be created. If it is a new tag,
677 * memory will be allocated when setting the values. Default values are 0 for for integer tags, 0.0 for double tags,
678 * 0 for entity handle tags.
679 *
680 * <B>Operations:</B> Collective
681 *
682 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
683 * \param[in] tag_storage_name (iMOAB_String) The tag name to store/retrieve the data in MOAB.
684 * \param[in] tag_type (int*) The type of MOAB tag (Dense/Sparse, Double/Int/EntityHandle), enum MOAB_TAG_TYPE.
685 * \param[in] components_per_entity (int*) The total size of vector dimension per entity for the tag (e.g., number of doubles per entity).
686 * \param[out] tag_index (int*) The tag index which can be used as identifier in synchronize methods.
687 * \return ErrCode The error code indicating success or failure.
688 */
689 ErrCode iMOAB_DefineTagStorage( iMOAB_AppID pid,
690 const iMOAB_String tag_storage_name,
691 int* tag_type,
692 int* components_per_entity,
693 int* tag_index );
694
695 /**
696 * \brief Store the specified values in a MOAB integer Tag.
697 *
698 * Values are set on vertices or elements, depending on entity_type
699 *
700 * \note we could change the api to accept as input the tag index, as returned by iMOAB_DefineTagStorage.
701 *
702 * <B>Operations:</B> Collective
703 *
704 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
705 * \param[in] tag_storage_name (iMOAB_String) The tag name to store/retreive the data in MOAB.
706 * \param[in] num_tag_storage_length (int*) The size of tag storage data (e.g., num_visible_vertices*components_per_entity or
707 * num_visible_elements*components_per_entity).
708 * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
709 * \param[out] tag_storage_data (int*) The array data of type <I>int</I> to replace the internal tag memory;
710 * The data is assumed to be contiguous over the local set of visible entities
711 * (either vertices or elements).
712 * \return ErrCode The error code indicating success or failure.
713 */
714 ErrCode iMOAB_SetIntTagStorage( iMOAB_AppID pid,
715 const iMOAB_String tag_storage_name,
716 int* num_tag_storage_length,
717 int* entity_type,
718 int* tag_storage_data );
719
720 /**
721 * \brief Get the specified values in a MOAB integer Tag.
722 *
723 * \note <B>Operations:</B> Collective
724 *
725 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
726 * \param[in] tag_storage_name (iMOAB_String) The tag name to store/retreive the data in MOAB.
727 * \param[in] num_tag_storage_length (int*) The size of tag storage data (e.g., num_visible_vertices*components_per_entity or
728 * num_visible_elements*components_per_entity).
729 * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
730 * \param[out] tag_storage_data (int*) The array data of type <I>int</I> to be copied from the internal tag memory;
731 * The data is assumed to be contiguous over the local set of visible
732 * entities (either vertices or elements).
733 * \return ErrCode The error code indicating success or failure.
734 */
735 ErrCode iMOAB_GetIntTagStorage( iMOAB_AppID pid,
736 const iMOAB_String tag_storage_name,
737 int* num_tag_storage_length,
738 int* entity_type,
739 int* tag_storage_data );
740
741 /**
742 * \brief Store the specified values in a MOAB double Tag.
743 *
744 * \note <B>Operations:</B> Collective
745 *
746 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
747 * \param[in] tag_storage_name (iMOAB_String) The tag names, separated, to store the data.
748 * \param[in] num_tag_storage_length (int*) The size of total tag storage data (e.g., num_visible_vertices*components_per_entity
749 * or num_visible_elements*components_per_entity*num_tags).
750 * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
751 * \param[out] tag_storage_data (double*) The array data of type <I>double</I> to replace the internal tag memory;
752 * The data is assumed to be contiguous over the local set of visible
753 * entities (either vertices or elements). unrolled by tags
754 * \return ErrCode The error code indicating success or failure.
755 */
756 ErrCode iMOAB_SetDoubleTagStorage( iMOAB_AppID pid,
757 const iMOAB_String tag_storage_name,
758 int* num_tag_storage_length,
759 int* entity_type,
760 double* tag_storage_data );
761
762 /**
763 * \brief Store the specified values in a MOAB double Tag, for given ids.
764 *
765 * \note <B>Operations:</B> Collective
766 *
767 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
768 * \param[in] tag_storage_name (iMOAB_String) The tag names, separated, to store the data.
769 * \param[in] num_tag_storage_length (int*) The size of total tag storage data (e.g., num_visible_vertices*components_per_entity
770 * or num_visible_elements*components_per_entity*num_tags).
771 * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
772 * \param[in] tag_storage_data (double*) The array data of type <I>double</I> to replace the internal tag memory;
773 * The data is assumed to be permuted over the local set of visible
774 * entities (either vertices or elements). unrolled by tags
775 * in parallel, might be different order, or different entities on the task
776 * \param[in] globalIds global ids of the cells to be set;
777 * \return ErrCode The error code indicating success or failure.
778 */
779
780 ErrCode iMOAB_SetDoubleTagStorageWithGid( iMOAB_AppID pid,
781 const iMOAB_String tag_storage_names,
782 int* num_tag_storage_length,
783 int* entity_type,
784 double* tag_storage_data,
785 int* globalIds );
786 /**
787 * \brief Retrieve the specified values in a MOAB double Tag.
788 *
789 * \note <B>Operations:</B> Collective
790 *
791 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
792 * \param[in] tag_storage_name (iMOAB_String) The tag names to retrieve the data in MOAB.
793 * \param[in] num_tag_storage_length (int) The size of total tag storage data (e.g., num_visible_vertices*components_per_entity*num_tags
794 * or num_visible_elements*components_per_entity*num_tags)
795 * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
796 * \param[out] tag_storage_data (double*) The array data of type <I>double</I> to replace the internal tag memory;
797 * The data is assumed to be contiguous over the local set of visible
798 * entities (either vertices or elements). unrolled by tags
799 * \return ErrCode The error code indicating success or failure.
800 */
801 ErrCode iMOAB_GetDoubleTagStorage( iMOAB_AppID pid,
802 const iMOAB_String tag_storage_name,
803 int* num_tag_storage_length,
804 int* entity_type,
805 double* tag_storage_data );
806
807 /**
808 * \brief Exchange tag values for the given tags across process boundaries.
809 *
810 * \note <B>Operations:</B> Collective
811 *
812 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
813 * \param[in] num_tags (int*) Number of tags to exchange.
814 * \param[in] tag_indices (int*) Array with tag indices of interest (size = *num_tags).
815 * \param[in] ent_type (int*) The type of entity for tag exchange.
816 * \return ErrCode The error code indicating success or failure.
817 */
818 ErrCode iMOAB_SynchronizeTags( iMOAB_AppID pid, int* num_tag, int* tag_indices, int* ent_type );
819
820 /**
821 * \brief Perform global reductions with the processes in the current applications communicator.
822 * Specifically this routine performs reductions on the maximum value of the tag indicated by \ref tag_index.
823 *
824 * \note <B>Operations:</B> Collective
825 *
826 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
827 * \param[in] tag_index (int*) The tag index of interest.
828 * \param[in] ent_type (int*) The type of entity for tag reduction operation
829 * (vertices = 0, elements = 1)
830 * \return ErrCode The error code indicating success or failure.
831 */
832 ErrCode iMOAB_ReduceTagsMax( iMOAB_AppID pid, int* tag_index, int* ent_type );
833
834 /**
835 * \brief Retrieve the adjacencies for the element entities.
836 *
837 * \note <B>Operations:</B> Not Collective
838 *
839 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
840 * \param[in] local_index (iMOAB_LocalID*) The local element ID for which adjacency information is needed.
841 * \param[out] num_adjacent_elements (int*) The total number of adjacent elements.
842 * \param[out] adjacent_element_IDs (iMOAB_LocalID*) The local element IDs of all adjacent elements to the current one
843 * (typically, num_total_sides for internal elements or
844 * num_total_sides-num_sides_on_boundary for boundary elements).
845 * \return ErrCode The error code indicating success or failure.
846 */
847 ErrCode iMOAB_GetNeighborElements( iMOAB_AppID pid,
848 iMOAB_LocalID* local_index,
849 int* num_adjacent_elements,
850 iMOAB_LocalID* adjacent_element_IDs );
851
852 /**
853 * \brief Get the adjacencies for the vertex entities.
854 *
855 * \todo The implementation may not be fully complete
856 *
857 * \note <B>Operations:</B> Not Collective
858 *
859 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
860 * \param[in] local_vertex_ID (iMOAB_LocalID*) The local vertex ID for which adjacency information is needed.
861 * \param[out] num_adjacent_vertices (int*) The total number of adjacent vertices.
862 * \param[out] adjacent_vertex_IDs (iMOAB_LocalID*) The local element IDs of all adjacent vertices to the current one
863 * (typically, num_total_sides for internal elements or
864 * num_total_sides-num_sides_on_boundary for boundary elements).
865 * \return ErrCode The error code indicating success or failure.
866 */
867 ErrCode iMOAB_GetNeighborVertices( iMOAB_AppID pid,
868 iMOAB_LocalID* local_vertex_ID,
869 int* num_adjacent_vertices,
870 iMOAB_LocalID* adjacent_vertex_IDs );
871
872 /**
873 * \brief Set global information for number of vertices and number of elements;
874 * It is usually available from the h5m file, or it can be computed with a MPI_Reduce.
875 *
876 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
877 * \param[in] num_global_verts (int*) The number of total vertices in the mesh.
878 * \param[in] num_global_elems (MPI_Comm) The number of total elements in the mesh.
879 * \return ErrCode The error code indicating success or failure.
880 */
881 ErrCode iMOAB_SetGlobalInfo( iMOAB_AppID pid, int* num_global_verts, int* num_global_elems );
882
883 /**
884 * \brief Get global information about number of vertices and number of elements.
885 *
886 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
887 * \param[in] num_global_verts (int*) The number of total vertices in the mesh.
888 * \param[in] num_global_elems (MPI_Comm) The number of total elements in the mesh.
889 * \return ErrCode The error code indicating success or failure.
890 */
891 ErrCode iMOAB_GetGlobalInfo( iMOAB_AppID pid, int* num_global_verts, int* num_global_elems );
892
893 #ifdef MOAB_HAVE_MPI
894
895 /**
896 * \brief migrate (send) a set of elements from a group of tasks (senders) to another group of tasks (receivers)
897 *
898 * \note <B>Operations:</B> Collective on sender group
899 *
900 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID of the sender mesh.
901 * \param[in] joint_communicator (MPI_Comm) The joint communicator that overlaps both the sender and receiver groups.
902 * \param[in] receivingGroup (MPI_Group *) Receiving group information.
903 * \param[in] rcompid (int*) External id of application that receives the mesh
904 * \param[in] method (int*) Partitioning ethod to use when sending the mesh;
905 * 0=trivial, 1=Zoltan Graph (PHG), 2=Zoltan Geometric (RCB).
906 * \return ErrCode The error code indicating success or failure.
907 */
908 ErrCode iMOAB_SendMesh( iMOAB_AppID pid,
909 MPI_Comm* joint_communicator,
910 MPI_Group* receivingGroup,
911 int* rcompid,
912 int* method );
913
914 /**
915 * \brief Free up all of the buffers that were allocated when data transfer between
916 * components are performed. The nonblocking send and receive call buffers will be de-allocated
917 * once all the data is received by all involved tasks.
918 *
919 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID sender mesh.
920 * \param[in] context_id (int*) The context used for sending, to identify the communication graph.
921 * \return ErrCode The error code indicating success of failure.
922 */
923 ErrCode iMOAB_FreeSenderBuffers( iMOAB_AppID pid, int* context_d );
924
925 /**
926 * \brief Migrate (receive) a set of elements from a sender group of tasks
927 *
928 * \note <B>Operations:</B> Collective on receiver group
929 *
930 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID mesh (receiver).
931 * \param[in] joint_communicator (MPI_Comm*) The joint communicator that overlaps both groups.
932 * \param[in] sending_group (MPI_Group *) The group of processes that are sending the mesh.
933 * \param[in] sender_comp_id ( int *) The unique application identifier that is sending the mesh
934 * \return ErrCode The error code indicating success or failure.
935 */
936 ErrCode iMOAB_ReceiveMesh( iMOAB_AppID pid,
937 MPI_Comm* joint_communicator,
938 MPI_Group* sending_group,
939 int* sender_comp_id );
940
941 /**
942 * \brief migrate (send) a list of tags, from a sender group of tasks to a receiver group of tasks
943 *
944 * \note <B>Operations:</B> Collective over the sender group, nonblocking sends
945 *
946 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID of sender mesh.
947 * \param[in] tag_storage_name (const iMOAB_String) The name of the tags to be sent between the processes.
948 * Generally multiple tag names are concatenated, separated by ";".
949 * \param[in] joint_communicator (MPI_Comm) The joint communicator that overlaps both groups.
950 * \param[in] context_id (int*) The identifier for the other participating component in the
951 * intersection context (typically target); -1 if this refers to
952 * the original migration of meshes (internal detail).
953 * \return ErrCode The error code indicating success or failure.
954 */
955 ErrCode iMOAB_SendElementTag( iMOAB_AppID pid,
956 const iMOAB_String tag_storage_name,
957 MPI_Comm* joint_communicator,
958 int* context_id );
959
960 /**
961 * \brief migrate (receive) a list of tags, from a sender group of tasks to a receiver group of tasks
962 *
963 * \note <B>Operations:</B> Collective over the receiver group, blocking receives
964 *
965 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID of receiver mesh.
966 * \param[in] tag_storage_name (const iMOAB_String) The name of the tags to be sent between the processes.
967 * Generally multiple tag names are concatenated, separated by ";".
968 * \param[in] joint_communicator (MPI_Comm) The joint communicator that overlaps both groups.
969 * \param[in] context_id (int*) The identifier for the other participating component in the
970 * intersection context (typically target); -1 if this refers to
971 * the original migration of meshes (internal detail).
972 * \return ErrCode The error code indicating success or failure.
973 */
974 ErrCode iMOAB_ReceiveElementTag( iMOAB_AppID pid,
975 const iMOAB_String tag_storage_name,
976 MPI_Comm* joint_communicator,
977 int* context_id );
978
979 /**
980 * \brief Compute a communication graph between 2 iMOAB applications, based on ID matching of key data.
981 *
982 * \note <B>Operations:</B> Collective
983 *
984 * \param[in] pid1 (iMOAB_AppID) The unique pointer to the first application ID.
985 * \param[in] pid2 (iMOAB_AppID) The unique pointer to the second application ID.
986 * \param[in] joint_communicator (MPI_Comm*) The MPI communicator that overlaps both groups.
987 * \param[in] group1 (MPI_Group *) MPI group for first component.
988 * \param[in] group2 (MPI_Group *) MPI group for second component.
989 * \param[in] type1 (int *) The type of mesh used by pid1 (spectral with GLOBAL_DOFS, etc).
990 * \param[in] type2 (int *) The type of mesh used by pid2 (point cloud with GLOBAL_ID, etc).
991 * \param[in] comp1 (int*) The unique identifier of the first component.
992 * \param[in] comp2 (int*) The unique identifier of the second component.
993 * \return ErrCode The error code indicating success or failure.
994 */
995 ErrCode iMOAB_ComputeCommGraph( iMOAB_AppID pid1,
996 iMOAB_AppID pid2,
997 MPI_Comm* joint_communicator,
998 MPI_Group* group1,
999 MPI_Group* group2,
1000 int* type1,
1001 int* type2,
1002 int* comp1,
1003 int* comp2 );
1004
1005 /**
1006 * \brief Recompute the communication graph between component and coupler, considering intersection coverage.
1007 *
1008 * \note Original communication graph for source used an initial partition, while during intersection some of the source
1009 * elements were sent to multiple tasks; send back the intersection coverage information for a direct communication
1010 * between source cx mesh on coupler tasks and source cc mesh on interested tasks on the component.
1011 * The intersection tasks will send to the original source component tasks, in a nonblocking way, the ids of all the
1012 * cells involved in intersection with the target cells. The new ParCommGraph between cc source mesh and cx source mesh
1013 * will be used just for tag migration, later on; The original ParCommGraph will stay unchanged, because this source mesh
1014 * could be used for other intersection (atm with lnd) ? on component source tasks, we will wait for information; from each
1015 * intersection task, will receive cells ids involved in intersection.
1016 *
1017 * \param[in] joint_communicator (MPI_Comm *) The joint communicator that overlaps component PEs and coupler PEs.
1018 * \param[in] pid_src (iMOAB_AppID) The unique application identifier for the component mesh on component PEs.
1019 * \param[in] pid_migr (iMOAB_AppID) The unique application identifier for the coupler mesh on coupler PEs.
1020 * \param[in] pid_intx (iMOAB_AppID) The unique application identifier representing the intersection context on coupler PEs.
1021 * \param[in] src_id (int*) The external id for the component mesh on component PE.
1022 * \param[in] migr_id (int*) The external id for the migrated mesh on coupler PEs.
1023 * \param[in] context_id (int*) The unique identifier of the other participating component in intersection (target).
1024 * \return ErrCode The error code indicating success or failure.
1025 */
1026 ErrCode iMOAB_CoverageGraph( MPI_Comm* joint_communicator,
1027 iMOAB_AppID pid_src,
1028 iMOAB_AppID pid_migr,
1029 iMOAB_AppID pid_intx,
1030 int* src_id,
1031 int* migr_id,
1032 int* context_id );
1033
1034 /**
1035 * \brief Dump info about communication graph.
1036 *
1037 * \note <B>Operations:</B> Collective per sender or receiver group
1038 *
1039 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
1040 * \param[in] context_id (int*) The context_id names are separated by a semi-colon (";");
1041 * This is similar to the specifications in tag migration.
1042 * \param[in] is_sender (int*) Specify whether it is called from sender or receiver side.
1043 * \param[in] prefix (iMOAB_String) The prefix for file names in order to differentiate different stages.
1044 * \return ErrCode The error code indicating success or failure.
1045 */
1046 ErrCode iMOAB_DumpCommGraph( iMOAB_AppID pid, int* context_id, int* is_sender, const iMOAB_String prefix );
1047
1048 /**
1049 * \brief merge vertices in an explicit, parallel mesh; it will also reassign global IDs on vertices,
1050 * and resolve parallel sharing of vertices.
1051 *
1052 * \note <B>Operations:</B> Collective
1053 *
1054 * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
1055 * \return ErrCode The error code indicating success or failure.
1056 */
1057 ErrCode iMOAB_MergeVertices( iMOAB_AppID pid );
1058
1059 /**
1060 * @brief Set the number of ghost layers for the map.
1061 *
1062 * @param[in] pid (iMOAB_AppID) The unique pointer to the map application ID.
1063 * @param[in] n_src_ghost_layers (int*) The number of ghost layers for source.
1064 * @param[in] n_tgt_ghost_layers (int*) The number of ghost layers for target.
1065 * @return ErrCode The error code indicating success or failure.
1066 */
1067 ErrCode iMOAB_SetMapGhostLayers( iMOAB_AppID pid, int* n_src_ghost_layers, int* n_tgt_ghost_layers );
1068
1069 #endif /* #ifdef MOAB_HAVE_MPI */
1070
1071 #ifdef MOAB_HAVE_TEMPESTREMAP
1072
1073 /**
1074 * @brief Compute intersection of the surface meshes defined on a sphere. The resulting intersected mesh consists
1075 * of (convex) polygons with 1-1 associativity with both the source and destination meshes provided.
1076 *
1077 * \note The mesh intersection between two heterogeneous resolutions will be computed and stored in the fileset
1078 * corresponding to the \p pid_intersection application. This intersection data can be used to compute solution
1079 * projection weights between these meshes.
1080 *
1081 * <B>Operations:</B> Collective on coupler tasks
1082 *
1083 * \param[in] pid_source (iMOAB_AppID) The unique pointer to the source application ID.
1084 * \param[in] pid_target (iMOAB_AppID) The unique pointer to the destination application ID.
1085 * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1086 * \return ErrCode The error code indicating success or failure.
1087 */
1088 ErrCode iMOAB_ComputeMeshIntersectionOnSphere( iMOAB_AppID pid_source,
1089 iMOAB_AppID pid_target,
1090 iMOAB_AppID pid_intersection );
1091
1092 /**
1093 * \brief Compute the intersection of DoFs corresponding to surface meshes defined on a sphere. The resulting intersected
1094 * mesh essentially contains a communication pattern or a permutation matrix that couples both the source and destination
1095 * DoFs.
1096 *
1097 * \note <B>Operations:</B> Collective on coupler tasks
1098 *
1099 * \param[in] pid_source (iMOAB_AppID) The unique pointer to the source application ID.
1100 * \param[in] pid_target (iMOAB_AppID) The unique pointer to the destination application ID.
1101 * \param[out] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1102 * \return ErrCode The error code indicating success or failure.
1103 */
1104 ErrCode iMOAB_ComputePointDoFIntersection( iMOAB_AppID pid_source,
1105 iMOAB_AppID pid_target,
1106 iMOAB_AppID pid_intersection );
1107
1108 #ifdef MOAB_HAVE_NETCDF
1109
1110 #ifdef MOAB_HAVE_MPI
1111
1112 /**
1113 * \brief Compute a communication graph between 2 moab apps, based on ID matching, between a component and map that
1114 * was read on coupler.
1115 *
1116 * \note Component can be target or source; also migrate meshes to coupler, from the components;
1117 * the mesh on coupler will be either source-like == coverage mesh or target-like the map is usually read
1118 * with rows fully distributed on tasks, so the target mesh will be a proper partition, while source mesh
1119 * coverage is dictated by the active columns on respective tasks.
1120 *
1121 * <B>Operations:</B> Collective
1122 *
1123 * \param[in] pid1 (iMOAB_AppID) The unique pointer to the first component.
1124 * \param[in] pid2 (iMOAB_AppID) The unique pointer to the second component.
1125 * \param[in] pid3 (iMOAB_AppID) The unique pointer to the coupler instance of the mesh (component 2).
1126 * \param[in] join (MPI_Comm) The joint communicator that overlaps both groups.
1127 * \param[in] group1 (MPI_Group *) The MPI group for the first component.
1128 * \param[in] group2 (MPI_Group *) The MPI group for the second component.
1129 * \param[in] type1 (int *) The type of mesh being migrated;
1130 * (1) spectral with GLOBAL_DOFS, (2) Point Cloud (3) FV cell.
1131 * \param[in] comp1 (int*) The universally unique identifier of first component.
1132 * \param[in] comp2 (int*) The universally unique identifier of second component.
1133 * \param[in] direction (int*) A parameter indicating direction of the mesh migration.
1134 * i.e., whether it is from source to coupler (1), or from coupler to target (2).
1135 * \return ErrCode The error code indicating success or failure.
1136 */
1137 ErrCode iMOAB_MigrateMapMesh( iMOAB_AppID pid1,
1138 iMOAB_AppID pid2,
1139 iMOAB_AppID pid3,
1140 MPI_Comm* join,
1141 MPI_Group* group1,
1142 MPI_Group* group2,
1143 int* type,
1144 int* comp1,
1145 int* comp2,
1146 int* direction );
1147
1148 #endif /* #ifdef MOAB_HAVE_MPI */
1149
1150 /**
1151 * \brief Load the projection weights from disk to transfer a solution from a source surface mesh to a destination mesh defined on a sphere.
1152 * The intersection of the mesh should be computed a-priori.
1153 *
1154 * <B>Operations:</B> Collective
1155 *
1156 * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the application ID to store the map
1157 * \param[in] pid_cpl (iMOAB_AppID) The unique pointer to coupler instance of component; (-1) for old load
1158 * \param[in] col_or_row (int *) The flag to indicate whether distribution is according to source (0) or target grid (1)
1159 * \param[in] type (int *) type of mesh (1) spectral with GLOBAL_DOFS, (2) Point Cloud (3) FV cell
1160 * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1161 * values could be identifiers such as "scalar", "flux" or "custom".
1162 * \param[in] remap_weights_filename (iMOAB_String) The filename path to the mapping file to load in memory.
1163 */
1164 ErrCode iMOAB_LoadMappingWeightsFromFile(
1165 iMOAB_AppID pid_intersection,
1166 iMOAB_AppID pid_cpl,
1167 int* col_or_row,
1168 int* type,
1169 const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1170 const iMOAB_String remap_weights_filename );
1171
1172 /**
1173 * \brief Write the projection weights to disk in order to transfer a solution from a source surface mesh to a destination
1174 * mesh defined on a sphere.
1175 *
1176 * \note <B>Operations:</B> Collective
1177 *
1178 * \param[in/out] pid_intersection (iMOAB_AppID) The unique pointer to the application ID to store the map.
1179 * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1180 * values could be identifiers such as "scalar", "flux" or "custom".
1181 * \param[in] remap_weights_filename (iMOAB_String) The filename path to the mapping file to load in memory.
1182 * \return ErrCode The error code indicating success or failure.
1183 */
1184 ErrCode iMOAB_WriteMappingWeightsToFile(
1185 iMOAB_AppID pid_intersection,
1186 const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1187 const iMOAB_String remap_weights_filename );
1188
1189 #endif /* #ifdef MOAB_HAVE_NETCDF */
1190
1191 /**
1192 * \brief Compute the projection weights to transfer a solution from a source surface mesh to a destination mesh defined
1193 * on a sphere. The intersection of the mesh should be computed a-priori.
1194 *
1195 * \note
1196 * The mesh intersection data-structure is used along with conservative remapping techniques in TempestRemap to compute
1197 * the projection weights for transferring the tag (\p soln_tag_name) from \p pid_src to \p pid_target applications.
1198 *
1199 * <B>Operations:</B> Collective
1200 *
1201 * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1202 * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1203 * values could be identifiers such as "scalar", "flux" or "custom".
1204 * \param[in] disc_method_source (iMOAB_String) The discretization type ("fv", "cgll", "dgll") for the solution field on the source grid.
1205 * \param[in] disc_order_source (int *) The discretization order for the solution field on the source grid.
1206 * \param[in] disc_method_target (iMOAB_String) The discretization type ("fv", "cgll", "dgll") for the solution field on the source grid.
1207 * \param[in] disc_order_target (int *) The discretization order for the solution field on the source grid.
1208 * \param[in] fNoBubble (int *) The flag to indicate whether to use bubbles in the interior of SE nodes.
1209 * Default: true i.e., no bubbles used.
1210 * \param[in] fMonotoneTypeID (int *) The flag to indicate whether solution monotonicity is to be preserved. 0: none, 1: mono.
1211 * \param[in] fVolumetric (int *) The flag to indicate whether we need to compute volumetric projection weights.
1212 * \param[in] fNoConservation (int *) The flag to indicate whether to ignore conservation of solution field during projection.
1213 * \param[in] fValidate (int *) The flag to indicate whether to validate the consistency and conservation of solution field during projection;
1214 * Production runs should not have this flag enabled to minimize collective operations.
1215 * \param[in] source_solution_tag_dof_name (iMOAB_String) The global DoF IDs corresponding to participating degrees-of-freedom for the source discretization.
1216 * \param[in] target_solution_tag_dof_name (iMOAB_String) The global DoF IDs corresponding to participating degrees-of-freedom for the target discretization.
1217 * \return ErrCode The error code indicating success or failure.
1218 */
1219 ErrCode iMOAB_ComputeScalarProjectionWeights(
1220 iMOAB_AppID pid_intersection,
1221 const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1222 const iMOAB_String disc_method_source,
1223 int* disc_order_source,
1224 const iMOAB_String disc_method_target,
1225 int* disc_order_target,
1226 const iMOAB_String fv_method,
1227 int* fNoBubble,
1228 int* fMonotoneTypeID,
1229 int* fVolumetric,
1230 int* fInverseDistanceMap,
1231 int* fNoConservation,
1232 int* fValidate,
1233 const iMOAB_String source_solution_tag_dof_name,
1234 const iMOAB_String target_solution_tag_dof_name );
1235
1236 /**
1237 * \brief Apply the projection weights matrix operator onto the source tag in order to compute the solution (tag)
1238 * represented on the target grid. This operation can be understood as the application of a matrix vector product
1239 * (Y=P*X).
1240 *
1241 * \note <B>Operations:</B> Collective
1242 *
1243 * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1244 * \param[in] filter_type (int) Value specifying whether to use a nonlinear filter for property preservation.
1245 default (none) = 0, global = 1, local = 2, patch = 3
1246 * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1247 * values could be identifiers such as "scalar", "flux" or "custom".
1248 * \param[in] source_solution_tag_name (iMOAB_String) list of tag names corresponding to participating degrees-of-freedom for the source discretization;
1249 * names are separated by ";", the same way as for tag migration.
1250 * \param[in] target_solution_tag_name (iMOAB_String) list of tag names corresponding to participating degrees-of-freedom for the target discretization;
1251 * names are separated by ";", the same way as for tag migration.
1252 * \return ErrCode The error code indicating success or failure.
1253 */
1254 ErrCode iMOAB_ApplyScalarProjectionWeights(
1255 iMOAB_AppID pid_intersection,
1256 int* filter_type, /* CAAS_NONE = 0, CAAS_GLOBAL = 1, CAAS_LOCAL = 2, CAAS_LOCAL_ADJACENT = 3 */
1257 const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1258 const iMOAB_String source_solution_tag_name,
1259 const iMOAB_String target_solution_tag_name );
1260
1261 #endif /* #ifdef MOAB_HAVE_TEMPESTREMAP */
1262
1263 #ifdef MOAB_HAVE_MPI
1264
1265 /**
1266 * Helper functions for MPI type conversions between Fortran and C++
1267 */
1268
1269 /**
1270 * \brief MOAB MPI helper function to convert from a C-based MPI_Comm object
1271 * to a Fortran compatible MPI_Fint (integer) value.
1272 *
1273 * \param comm Input MPI_Comm C-object pointer.
1274 * \return MPI_Fint Output Fortran integer representing the comm object.
1275 */
1276 inline MPI_Fint MOAB_MPI_Comm_c2f( MPI_Comm* comm )
1277 {
1278 return MPI_Comm_c2f( *comm );
1279 }
1280
1281 /**
1282 * \brief MOAB MPI helper function to convert from a Fortran-based MPI_Fint (integer)
1283 * value to a C/C++ compatible MPI_Comm object.
1284 *
1285 * \param fgroup (MPI_Fint) Input Fortran integer representing the MPI_Comm object.
1286 * \return MPI_Comm* Output C/C++-compatible MPI_Comm object pointer.
1287 */
1288 inline MPI_Comm* MOAB_MPI_Comm_f2c( MPI_Fint fcomm )
1289 {
1290 MPI_Comm* ccomm;
1291 ccomm = (MPI_Comm*)( malloc( sizeof( MPI_Comm ) ) ); // memory leak ?!
1292 *ccomm = MPI_Comm_f2c( fcomm );
1293 if( *ccomm == MPI_COMM_NULL )
1294 {
1295 free( ccomm );
1296 IMOAB_THROW_ERROR( "The MPI_Comm conversion from Fortran to C failed.", NULL );
1297 }
1298 else
1299 return ccomm;
1300 }
1301
1302 /**
1303 * \brief MOAB MPI helper functions to convert from a C-based MPI_Group object
1304 * to a Fortran compatible MPI_Fint (integer) value.
1305 *
1306 * \param group Input MPI_Comm C-object pointer.
1307 * \return MPI_Fint Output Fortran integer representing the comm object.
1308 */
1309 inline MPI_Fint MOAB_MPI_Group_c2f( MPI_Group* group )
1310 {
1311 return MPI_Group_c2f( *group );
1312 }
1313
1314 /**
1315 * \brief MOAB MPI helper function to convert from a Fortran-based MPI_Fint (integer)
1316 * value to a C/C++ compatible MPI_Group object.
1317 *
1318 * \param fgroup (MPI_Fint) Input Fortran integer representing the MPIGroup object.
1319 * \return MPI_Group* Output C/C++-compatible MPI_Group object pointer.
1320 */
1321 inline MPI_Group* MOAB_MPI_Group_f2c( MPI_Fint fgroup )
1322 {
1323 MPI_Group* cgroup;
1324 cgroup = (MPI_Group*)( malloc( sizeof( MPI_Group ) ) ); // memory leak ?!
1325 *cgroup = MPI_Group_f2c( fgroup );
1326 if( *cgroup == MPI_GROUP_NULL )
1327 {
1328 free( cgroup );
1329 IMOAB_THROW_ERROR( "The MPI_Group conversion from Fortran to C failed.", NULL );
1330 }
1331 else
1332 return cgroup;
1333 }
1334
1335 #endif /* #ifdef MOAB_HAVE_MPI */
1336
1337 #ifdef __cplusplus
1338 }
1339 #endif /* #ifdef __cplusplus */
1340
1341 #endif /* #ifndef IMOAB_H */
1.9.1.