Mesh Oriented datABase  (version 5.6.0)
An array-based unstructured mesh library
iMOAB.h
Go to the documentation of this file.
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 #ifdef MOAB_HAVE_MPI
327 
328 /**
329  * \brief Resolve shared entities using global markers on shared vertices.
330  *
331  * \note Global markers can be a global node id, for example, or a global DoF number (as for HOMME)
332  *
333  * <B>Operations:</B> Collective .
334  *
335  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
336  * \param[in] num_verts (int*) Number of vertices.
337  * \param[in] marker (int*) Resolving marker (global id marker).
338  * \return ErrCode The error code indicating success or failure.
339  */
340 ErrCode iMOAB_ResolveSharedEntities( iMOAB_AppID pid, int* num_verts, int* marker );
341 
342 /**
343  * \brief Create the requested number of ghost layers for the parallel mesh.
344  *
345  * \note The routine assumes that the shared entities were resolved successfully, and that
346  * the mesh is properly distributed on separate tasks.
347  *
348  * <B>Operations:</B> Collective.
349  *
350  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
351  * \param[in] ghost_dim (int*) Desired ghost dimension (2 or 3, most of the time).
352  * \param[in] num_ghost_layers (int*) Number of ghost layers requested.
353  * \param[in] bridge_dim (int*) Bridge dimension (0 for vertices, 1 for edges, 2 for faces).
354  * \return ErrCode The error code indicating success or failure.
355  */
356 ErrCode iMOAB_DetermineGhostEntities( iMOAB_AppID pid, int* ghost_dim, int* num_ghost_layers, int* bridge_dim );
357 
358 #endif /* #ifdef MOAB_HAVE_MPI */
359 
360 /**
361  * \brief Write a MOAB mesh along with the solution tags to a file.
362  *
363  * \note The interface will write one single file (H5M) and for serial files (VTK/Exodus), it will write one
364  * file per task. Write options include parallel write options, if needed. Only the mesh set and solution data
365  * associated to the application will be written to the file.
366  *
367  * <B>Operations:</B> Collective for parallel write, non collective for serial write.
368  *
369  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
370  * \param[in] filename (iMOAB_String) The MOAB mesh file (H5M) to write all the entities contained in the
371  * internal application mesh set.
372  * \param[in] write_options (iMOAB_String) Additional options for writing the MOAB mesh in parallel.
373  * \return ErrCode The error code indicating success or failure.
374  */
375 ErrCode iMOAB_WriteMesh( iMOAB_AppID pid, const iMOAB_String filename, const iMOAB_String write_options );
376 
377 /**
378  * \brief Write a local MOAB mesh copy.
379  *
380  * \note The interface will write one file per task. Only the local mesh set and solution data associated
381  * to the application will be written to the file. Very convenient method used for debugging.
382  *
383  * <B>Operations:</B> Not Collective (independent operation).
384  *
385  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
386  * \param[in] prefix (iMOAB_String) The MOAB file prefix that will be used with task ID in parallel.
387  * \return ErrCode The error code indicating success or failure.
388  */
389 ErrCode iMOAB_WriteLocalMesh( iMOAB_AppID pid, iMOAB_String prefix );
390 
391 /**
392  * \brief Update local mesh data structure, from file information.
393  *
394  * \note The method should be called after mesh modifications, for example reading a file or creating mesh in memory
395  *
396  * <B>Operations:</B> Collective
397  *
398  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
399  * \return ErrCode The error code indicating success or failure.
400  */
401 ErrCode iMOAB_UpdateMeshInfo( iMOAB_AppID pid );
402 
403 /**
404  * \brief Retrieve all the important mesh information related to vertices, elements, vertex and surface boundary conditions.
405  *
406  * \note Number of visible vertices and cells include ghost entities. All arrays returned have size 3.
407  * Local entities are first, then ghost entities are next. Shared vertices can be owned in MOAB sense by
408  * different tasks. Ghost vertices and cells are always owned by other tasks.
409  *
410  * <B>Operations:</B> Not Collective
411  *
412  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
413  * \param[out] num_visible_vertices (int*) The number of vertices in the current partition/process arranged.
414  * as: owned/shared only, ghosted, total_visible (array allocated by
415  * user, <TT>size := 3</TT>).
416  * \param[out] num_visible_elements (int*) The number of elements in current partition/process arranged as: owned only,
417  * ghosted/shared, total_visible (array allocated by user, <TT>size := 3</TT>).
418  * \param[out] num_visible_blocks (int*) The number of material sets in local mesh in current partition/process
419  * arranged as: owned only, ghosted/shared, total_visible (array allocated by
420  * user, <TT>size := 3</TT>).
421  * \param[out] num_visible_surfaceBC (int*) The number of mesh surfaces that have a NEUMANN_SET BC defined in local mesh
422  * in current partition/process arranged as: owned only, ghosted/shared,
423  * total_visible (array allocated by user, <TT>size := 3</TT>).
424  * \param[out] num_visible_vertexBC (int*) The number of vertices that have a DIRICHLET_SET BC defined in local mesh in
425  * current partition/process arranged as: owned only, ghosted/shared,
426  * total_visible (array allocated by user, <TT>size := 3</TT>).
427  * \return ErrCode The error code indicating success or failure.
428  */
429 ErrCode iMOAB_GetMeshInfo( iMOAB_AppID pid,
430  int* num_visible_vertices,
431  int* num_visible_elements,
432  int* num_visible_blocks,
433  int* num_visible_surfaceBC,
434  int* num_visible_vertexBC );
435 
436 /**
437  * \brief Get the global vertex IDs for all locally visible (owned and shared/ghosted) vertices.
438  *
439  * \note The array should be allocated by the user, sized with the total number of visible vertices
440  * from iMOAB_GetMeshInfo method.
441  *
442  * <B>Operations:</B> Not collective
443  *
444  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
445  * \param[in] vertices_length (int*) The allocated size of array
446  * (typical <TT>size := num_visible_vertices</TT>).
447  * \param[out] global_vertex_ID (iMOAB_GlobalID*) The global IDs for all locally visible
448  * vertices (array allocated by user).
449  * \return ErrCode The error code indicating success or failure.
450  */
451 ErrCode iMOAB_GetVertexID( iMOAB_AppID pid, int* vertices_length, iMOAB_GlobalID* global_vertex_ID );
452 
453 /**
454  * \brief Get vertex ownership information.
455  *
456  * For each vertex based on the local ID, return the process that owns the vertex (local, shared or ghost)
457  *
458  * \note Shared vertices could be owned by different tasks. Local and shared vertices are first, ghost
459  * vertices are next in the array. Ghost vertices are always owned by a different process ID. Array allocated
460  * by the user with total size of visible vertices.
461  *
462  * <B>Operations:</B> Not Collective
463  *
464  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
465  * \param[in] vertices_length (int*) The allocated size of array
466  * (typically <TT>size := num_visible_vertices</TT>).
467  * \param[out] visible_global_rank_ID (int*) The processor rank owning each of the local vertices.
468  * \return ErrCode The error code indicating success or failure.
469  */
470 ErrCode iMOAB_GetVertexOwnership( iMOAB_AppID pid, int* vertices_length, int* visible_global_rank_ID );
471 
472 /**
473  * \brief Get vertex coordinates for all local (owned and ghosted) vertices.
474  *
475  * \note coordinates are returned in an array allocated by user, interleaved. (do need an option for blocked
476  * coordinates ?) size of the array is dimension times number of visible vertices. The local ordering is implicit,
477  * owned/shared vertices are first, then ghosts.
478  *
479  * <B>Operations:</B> Not Collective
480  *
481  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
482  * \param[in] coords_length (int*) The size of the allocated coordinate array (array allocated by
483  * user, <TT>size := 3*num_visible_vertices</TT>).
484  * \param[out] coordinates (double*) The pointer to user allocated memory that will be filled with
485  * interleaved coordinates.
486  * \return ErrCode The error code indicating success or failure.
487  */
488 ErrCode iMOAB_GetVisibleVerticesCoordinates( iMOAB_AppID pid, int* coords_length, double* coordinates );
489 
490 /**
491  * \brief Get the global block IDs for all locally visible (owned and shared/ghosted) blocks.
492  *
493  * \note Block IDs are corresponding to MATERIAL_SET tags for material sets. Usually the block ID is exported
494  * from Cubit as a unique integer value. First blocks are local, and next blocks are fully ghosted. First blocks
495  * have at least one owned cell/element, ghost blocks have only ghost cells. Internally, a block corresponds to a
496  * mesh set with a MATERIAL_SET tag value equal to the block ID.
497  *
498  * <B>Operations:</B> Not Collective
499  *
500  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
501  * \param[in] block_length (int*) The allocated size of array
502  * (typical <TT>size := num_visible_blocks</TT>).
503  * \param[out] global_block_IDs (iMOAB_GlobalID*) The global IDs for all locally visible blocks
504  * (array allocated by user).
505  * \return ErrCode The error code indicating success or failure.
506  */
507 ErrCode iMOAB_GetBlockID( iMOAB_AppID pid, int* block_length, iMOAB_GlobalID* global_block_IDs );
508 
509 /**
510  * \brief Get the global block information and number of visible elements of belonging to a
511  * block (MATERIAL SET).
512  *
513  * \note A block has to be homogeneous, it can contain elements of a single type.
514  *
515  * <B>Operations:</B> Not Collective
516  *
517  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
518  * \param[in] global_block_ID (iMOAB_GlobalID) The global block ID of the set to be queried.
519  * \param[out] vertices_per_element (int*) The number of vertices per element.
520  * \param[out] num_elements_in_block (int*) The number of elements in block.
521  * \return ErrCode The error code indicating success or failure.
522  */
523 ErrCode iMOAB_GetBlockInfo( iMOAB_AppID pid,
524  iMOAB_GlobalID* global_block_ID,
525  int* vertices_per_element,
526  int* num_elements_in_block );
527 
528 /**
529  * \brief Get the visible elements information.
530  *
531  * Return for all visible elements the global IDs, ranks they belong to, block ids they belong to.
532  *
533  * \todo : Can we also return the index for each block ID?
534  *
535  * \note <B>Operations:</B> Not Collective
536  *
537  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
538  * \param[in] num_visible_elements (int*) The number of visible elements (returned by \c GetMeshInfo).
539  * \param[out] element_global_IDs (iMOAB_GlobalID*) Element global ids to be added to the block.
540  * \param[out] ranks (int*) The owning ranks of elements.
541  * \param[out] block_IDs (iMOAB_GlobalID*) The block ids containing the elements.
542  * \return ErrCode The error code indicating success or failure.
543  */
544 ErrCode iMOAB_GetVisibleElementsInfo( iMOAB_AppID pid,
545  int* num_visible_elements,
546  iMOAB_GlobalID* element_global_IDs,
547  int* ranks,
548  iMOAB_GlobalID* block_IDs );
549 
550 /**
551  * \brief Get the connectivities for elements contained within a certain block.
552  *
553  * \note input is the block ID. Should we change to visible block local index?
554  *
555  * <B>Operations:</B> Not Collective
556  *
557  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
558  * \param[in] global_block_ID (iMOAB_GlobalID*) The global block ID of the set being queried.
559  * \param[in] connectivity_length (int*) The allocated size of array.
560  * (typical <TT>size := vertices_per_element*num_elements_in_block</TT>)
561  * \param[out] element_connectivity (int*) The connectivity array to store element ordering in MOAB canonical
562  * numbering scheme (array allocated by user); array contains vertex
563  * indices in the local numbering order for vertices elements are in
564  * the same order as provided by GetElementOwnership and GetElementID.
565  * \return ErrCode The error code indicating success or failure.
566  */
567 ErrCode iMOAB_GetBlockElementConnectivities( iMOAB_AppID pid,
568  iMOAB_GlobalID* global_block_ID,
569  int* connectivity_length,
570  int* element_connectivity );
571 
572 /**
573  * \brief Get the connectivity for one element only.
574  *
575  * \note This is a convenience method and in general should not be used unless necessary.
576  * You should use colaesced calls for multiple elements for efficiency.
577  *
578  * <B>Operations:</B> Not Collective
579  *
580  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
581  * \param[in] elem_index (iMOAB_LocalID *) Local element index.
582  * \param[in,out] connectivity_length (int *) On input, maximum length of connectivity. On output, actual length.
583  * \param[out] element_connectivity (int*) The connectivity array to store connectivity in MOAB canonical numbering
584  * scheme. Array contains vertex indices in the local numbering order for
585  * vertices.
586  * \return ErrCode The error code indicating success or failure.
587  */
588 ErrCode iMOAB_GetElementConnectivity( iMOAB_AppID pid,
589  iMOAB_LocalID* elem_index,
590  int* connectivity_length,
591  int* element_connectivity );
592 
593 /**
594  * \brief Get the element ownership within a certain block i.e., processor ID of the element owner.
595  *
596  * \note : Should we use local block index for input, instead of the global block ID ?
597  *
598  * <B>Operations:</B> Not Collective
599  *
600  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
601  * \param[in] global_block_ID (iMOAB_GlobalID) The global block ID of the set being queried.
602  * \param[in] num_elements_in_block (int*) The allocated size of ownership array, same as
603  * <TT>num_elements_in_block</TT> returned from GetBlockInfo().
604  * \param[out] element_ownership (int*) The ownership array to store processor ID for all elements
605  * (array allocated by user).
606  * \return ErrCode The error code indicating success or failure.
607  */
608 ErrCode iMOAB_GetElementOwnership( iMOAB_AppID pid,
609  iMOAB_GlobalID* global_block_ID,
610  int* num_elements_in_block,
611  int* element_ownership );
612 
613 /**
614  * \brief Get the global IDs for all locally visible elements belonging to a particular block.
615  *
616  * \note The method will return also the local index of each element, in the local range that contains
617  * all visible elements.
618  *
619  * <B>Operations:</B> Not Collective
620  *
621  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
622  * \param[in] global_block_ID (iMOAB_GlobalID*) The global block ID of the set being queried.
623  * \param[in] num_elements_in_block (int*) The allocated size of global element ID array, same as
624  * <TT>num_elements_in_block</TT> returned from GetBlockInfo().
625  * \param[out] global_element_ID (iMOAB_GlobalID*) The global IDs for all locally visible elements
626  * (array allocated by user).
627  * \param[out] local_element_ID (iMOAB_LocalID*) (<I><TT>Optional</TT></I>) The local IDs for all locally visible
628  * elements (index in the range of all primary elements in the rank)
629  * \return ErrCode The error code indicating success or failure.
630  */
631 ErrCode iMOAB_GetElementID( iMOAB_AppID pid,
632  iMOAB_GlobalID* global_block_ID,
633  int* num_elements_in_block,
634  iMOAB_GlobalID* global_element_ID,
635  iMOAB_LocalID* local_element_ID );
636 
637 /**
638  * \brief Get the surface boundary condition information.
639  *
640  * \note <B>Operations:</B> Not Collective
641  *
642  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
643  * \param[in] surface_BC_length (int*) The allocated size of surface boundary condition array, same
644  * as <TT>num_visible_surfaceBC</TT> returned by GetMeshInfo().
645  * \param[out] local_element_ID (iMOAB_LocalID*) The local element IDs that contains the side with the surface BC.
646  * \param[out] reference_surface_ID (int*) The surface number with the BC in the canonical reference
647  * element (e.g., 1 to 6 for HEX, 1-4 for TET).
648  * \param[out] boundary_condition_value (int*) The boundary condition type as obtained from the mesh description
649  * (value of the NeumannSet defined on the element).
650  * \return ErrCode The error code indicating success or failure.
651  */
652 ErrCode iMOAB_GetPointerToSurfaceBC( iMOAB_AppID pid,
653  int* surface_BC_length,
654  iMOAB_LocalID* local_element_ID,
655  int* reference_surface_ID,
656  int* boundary_condition_value );
657 
658 /**
659  * \brief Get the vertex boundary condition information.
660  *
661  * \note <B>Operations:</B> Not Collective
662  *
663  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
664  * \param[in] vertex_BC_length (int) The allocated size of vertex boundary condition array, same as
665  * <TT>num_visible_vertexBC</TT> returned by GetMeshInfo().
666  * \param[out] local_vertex_ID (iMOAB_LocalID*) The local vertex ID that has Dirichlet BC defined.
667  * \param[out] boundary_condition_value (int*) The boundary condition type as obtained from the mesh description
668  * (value of the Dirichlet_Set tag defined on the vertex).
669  * \return ErrCode The error code indicating success or failure.
670  */
671 ErrCode iMOAB_GetPointerToVertexBC( iMOAB_AppID pid,
672  int* vertex_BC_length,
673  iMOAB_LocalID* local_vertex_ID,
674  int* boundary_condition_value );
675 
676 /**
677  * \brief Define a MOAB Tag corresponding to the application depending on requested types.
678  *
679  * \note In MOAB, for most solution vectors, we only need to create a "Dense", "Double" Tag. A sparse tag can
680  * be created too. If the tag is already existing in the file, it will not be created. If it is a new tag,
681  * memory will be allocated when setting the values. Default values are 0 for for integer tags, 0.0 for double tags,
682  * 0 for entity handle tags.
683  *
684  * <B>Operations:</B> Collective
685  *
686  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
687  * \param[in] tag_storage_name (iMOAB_String) The tag name to store/retrieve the data in MOAB.
688  * \param[in] tag_type (int*) The type of MOAB tag (Dense/Sparse, Double/Int/EntityHandle), enum MOAB_TAG_TYPE.
689  * \param[in] components_per_entity (int*) The total size of vector dimension per entity for the tag (e.g., number of doubles per entity).
690  * \param[out] tag_index (int*) The tag index which can be used as identifier in synchronize methods.
691  * \return ErrCode The error code indicating success or failure.
692  */
693 ErrCode iMOAB_DefineTagStorage( iMOAB_AppID pid,
694  const iMOAB_String tag_storage_name,
695  int* tag_type,
696  int* components_per_entity,
697  int* tag_index );
698 
699 /**
700  * \brief Store the specified values in a MOAB integer Tag.
701  *
702  * Values are set on vertices or elements, depending on entity_type
703  *
704  * \note we could change the api to accept as input the tag index, as returned by iMOAB_DefineTagStorage.
705  *
706  * <B>Operations:</B> Collective
707  *
708  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
709  * \param[in] tag_storage_name (iMOAB_String) The tag name to store/retreive the data in MOAB.
710  * \param[in] num_tag_storage_length (int*) The size of tag storage data (e.g., num_visible_vertices*components_per_entity or
711  * num_visible_elements*components_per_entity).
712  * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
713  * \param[out] tag_storage_data (int*) The array data of type <I>int</I> to replace the internal tag memory;
714  * The data is assumed to be contiguous over the local set of visible entities
715  * (either vertices or elements).
716  * \return ErrCode The error code indicating success or failure.
717  */
718 ErrCode iMOAB_SetIntTagStorage( iMOAB_AppID pid,
719  const iMOAB_String tag_storage_name,
720  int* num_tag_storage_length,
721  int* entity_type,
722  int* tag_storage_data );
723 
724 /**
725  * \brief Get the specified values in a MOAB integer Tag.
726  *
727  * \note <B>Operations:</B> Collective
728  *
729  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
730  * \param[in] tag_storage_name (iMOAB_String) The tag name to store/retreive the data in MOAB.
731  * \param[in] num_tag_storage_length (int*) The size of tag storage data (e.g., num_visible_vertices*components_per_entity or
732  * num_visible_elements*components_per_entity).
733  * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
734  * \param[out] tag_storage_data (int*) The array data of type <I>int</I> to be copied from the internal tag memory;
735  * The data is assumed to be contiguous over the local set of visible
736  * entities (either vertices or elements).
737  * \return ErrCode The error code indicating success or failure.
738  */
739 ErrCode iMOAB_GetIntTagStorage( iMOAB_AppID pid,
740  const iMOAB_String tag_storage_name,
741  int* num_tag_storage_length,
742  int* entity_type,
743  int* tag_storage_data );
744 
745 /**
746  * \brief Store the specified values in a MOAB double Tag.
747  *
748  * \note <B>Operations:</B> Collective
749  *
750  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
751  * \param[in] tag_storage_name (iMOAB_String) The tag names, separated, to store the data.
752  * \param[in] num_tag_storage_length (int*) The size of total tag storage data (e.g., num_visible_vertices*components_per_entity
753  * or num_visible_elements*components_per_entity*num_tags).
754  * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
755  * \param[out] tag_storage_data (double*) The array data of type <I>double</I> to replace the internal tag memory;
756  * The data is assumed to be contiguous over the local set of visible
757  * entities (either vertices or elements). unrolled by tags
758  * \return ErrCode The error code indicating success or failure.
759  */
760 ErrCode iMOAB_SetDoubleTagStorage( iMOAB_AppID pid,
761  const iMOAB_String tag_storage_name,
762  int* num_tag_storage_length,
763  int* entity_type,
764  double* tag_storage_data );
765 
766 /**
767  * \brief Store the specified values in a MOAB double Tag, for given ids.
768  *
769  * \note <B>Operations:</B> Collective
770  *
771  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
772  * \param[in] tag_storage_name (iMOAB_String) The tag names, separated, to store the data.
773  * \param[in] num_tag_storage_length (int*) The size of total tag storage data (e.g., num_visible_vertices*components_per_entity
774  * or num_visible_elements*components_per_entity*num_tags).
775  * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
776  * \param[in] tag_storage_data (double*) The array data of type <I>double</I> to replace the internal tag memory;
777  * The data is assumed to be permuted over the local set of visible
778  * entities (either vertices or elements). unrolled by tags
779  * in parallel, might be different order, or different entities on the task
780  * \param[in] globalIds global ids of the cells to be set;
781  * \return ErrCode The error code indicating success or failure.
782  */
783 
784 ErrCode iMOAB_SetDoubleTagStorageWithGid( iMOAB_AppID pid,
785  const iMOAB_String tag_storage_names,
786  int* num_tag_storage_length,
787  int* entity_type,
788  double* tag_storage_data,
789  int* globalIds );
790 
791 #ifdef MOAB_HAVE_TEMPESTREMAP
792 /**
793  * \brief Get the number of 2D entities in the TempestRemap CoveringMesh of this app, and
794  * optionally their global IDs and centroid coordinates.
795  *
796  * Useful for populating analytic source fields directly on the coverage cells of a
797  * dual-map intersection app, bypassing partition-dependent migration paths. This makes
798  * BFB testing of dual-map CAAS robust against rank-count differences in the source
799  * partition.
800  *
801  * Call once with gids=NULL, centroids=NULL to query num_cov_elems, then allocate and
802  * call again to fill the output buffers.
803  *
804  * \param[in] pid Application ID with an attached TempestRemap remapper.
805  * \param[inout] num_cov_elems On output: number of covering 2D entities on this rank.
806  * \param[out] gids Optional. If non-null, filled with global IDs.
807  * \param[out] centroids Optional. If non-null, filled with element centroids
808  * (size 3*num_cov_elems, x,y,z interleaved).
809  */
810 ErrCode iMOAB_GetCoverageMeshInfo( iMOAB_AppID pid, int* num_cov_elems, int* gids, double* centroids );
811 
812 /**
813  * \brief Set a double tag on every entity of the TempestRemap CoveringMesh of this app.
814  *
815  * Values are written in the same order as iMOAB_GetCoverageMeshInfo returns gids.
816  * The tag must already be defined on the app via iMOAB_DefineTagStorage.
817  *
818  * \param[in] pid Application ID with an attached TempestRemap remapper.
819  * \param[in] tag_storage_name Name of the (already-defined) double tag.
820  * \param[in] num_tag_storage_length Total number of values supplied (= num_cov_elems *
821  * components_per_entity).
822  * \param[in] tag_storage_data The values to write, in covering-Range order.
823  */
824 ErrCode iMOAB_SetDoubleTagStorageOnCoverage( iMOAB_AppID pid,
825  const iMOAB_String tag_storage_name,
826  int* num_tag_storage_length,
827  double* tag_storage_data );
828 #endif
829 
830 /**
831  * \brief Retrieve the specified values in a MOAB double Tag.
832  *
833  * \note <B>Operations:</B> Collective
834  *
835  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
836  * \param[in] tag_storage_name (iMOAB_String) The tag names to retrieve the data in MOAB.
837  * \param[in] num_tag_storage_length (int) The size of total tag storage data (e.g., num_visible_vertices*components_per_entity*num_tags
838  * or num_visible_elements*components_per_entity*num_tags)
839  * \param[in] entity_type (int*) Type=0 for vertices, and Type=1 for primary elements.
840  * \param[out] tag_storage_data (double*) The array data of type <I>double</I> to replace the internal tag memory;
841  * The data is assumed to be contiguous over the local set of visible
842  * entities (either vertices or elements). unrolled by tags
843  * \return ErrCode The error code indicating success or failure.
844  */
845 ErrCode iMOAB_GetDoubleTagStorage( iMOAB_AppID pid,
846  const iMOAB_String tag_storage_name,
847  int* num_tag_storage_length,
848  int* entity_type,
849  double* tag_storage_data );
850 
851 /**
852  * \brief Exchange tag values for the given tags across process boundaries.
853  *
854  * \note <B>Operations:</B> Collective
855  *
856  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
857  * \param[in] num_tags (int*) Number of tags to exchange.
858  * \param[in] tag_indices (int*) Array with tag indices of interest (size = *num_tags).
859  * \param[in] ent_type (int*) The type of entity for tag exchange.
860  * \return ErrCode The error code indicating success or failure.
861  */
862 ErrCode iMOAB_SynchronizeTags( iMOAB_AppID pid, int* num_tag, int* tag_indices, int* ent_type );
863 
864 /**
865  * \brief Perform global reductions with the processes in the current applications communicator.
866  * Specifically this routine performs reductions on the maximum value of the tag indicated by \ref tag_index.
867  *
868  * \note <B>Operations:</B> Collective
869  *
870  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
871  * \param[in] tag_index (int*) The tag index of interest.
872  * \param[in] ent_type (int*) The type of entity for tag reduction operation
873  * (vertices = 0, elements = 1)
874  * \return ErrCode The error code indicating success or failure.
875  */
876 ErrCode iMOAB_ReduceTagsMax( iMOAB_AppID pid, int* tag_index, int* ent_type );
877 
878 /**
879  * \brief Retrieve the adjacencies for the element entities.
880  *
881  * \note <B>Operations:</B> Not Collective
882  *
883  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
884  * \param[in] local_index (iMOAB_LocalID*) The local element ID for which adjacency information is needed.
885  * \param[out] num_adjacent_elements (int*) The total number of adjacent elements.
886  * \param[out] adjacent_element_IDs (iMOAB_LocalID*) The local element IDs of all adjacent elements to the current one
887  * (typically, num_total_sides for internal elements or
888  * num_total_sides-num_sides_on_boundary for boundary elements).
889  * \return ErrCode The error code indicating success or failure.
890  */
891 ErrCode iMOAB_GetNeighborElements( iMOAB_AppID pid,
892  iMOAB_LocalID* local_index,
893  int* num_adjacent_elements,
894  iMOAB_LocalID* adjacent_element_IDs );
895 
896 /**
897  * \brief Get the adjacencies for the vertex entities.
898  *
899  * \todo The implementation may not be fully complete
900  *
901  * \note <B>Operations:</B> Not Collective
902  *
903  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
904  * \param[in] local_vertex_ID (iMOAB_LocalID*) The local vertex ID for which adjacency information is needed.
905  * \param[out] num_adjacent_vertices (int*) The total number of adjacent vertices.
906  * \param[out] adjacent_vertex_IDs (iMOAB_LocalID*) The local element IDs of all adjacent vertices to the current one
907  * (typically, num_total_sides for internal elements or
908  * num_total_sides-num_sides_on_boundary for boundary elements).
909  * \return ErrCode The error code indicating success or failure.
910  */
911 ErrCode iMOAB_GetNeighborVertices( iMOAB_AppID pid,
912  iMOAB_LocalID* local_vertex_ID,
913  int* num_adjacent_vertices,
914  iMOAB_LocalID* adjacent_vertex_IDs );
915 
916 /**
917  * \brief Set global information for number of vertices and number of elements;
918  * It is usually available from the h5m file, or it can be computed with a MPI_Reduce.
919  *
920  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
921  * \param[in] num_global_verts (int*) The number of total vertices in the mesh.
922  * \param[in] num_global_elems (MPI_Comm) The number of total elements in the mesh.
923  * \return ErrCode The error code indicating success or failure.
924  */
925 ErrCode iMOAB_SetGlobalInfo( iMOAB_AppID pid, int* num_global_verts, int* num_global_elems );
926 
927 /**
928  * \brief Get global information about number of vertices and number of elements.
929  *
930  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
931  * \param[in] num_global_verts (int*) The number of total vertices in the mesh.
932  * \param[in] num_global_elems (MPI_Comm) The number of total elements in the mesh.
933  * \return ErrCode The error code indicating success or failure.
934  */
935 ErrCode iMOAB_GetGlobalInfo( iMOAB_AppID pid, int* num_global_verts, int* num_global_elems );
936 
937 #ifdef MOAB_HAVE_MPI
938 
939 /**
940  * \brief migrate (send) a set of elements from a group of tasks (senders) to another group of tasks (receivers)
941  *
942  * \note <B>Operations:</B> Collective on sender group
943  *
944  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID of the sender mesh.
945  * \param[in] joint_communicator (MPI_Comm) The joint communicator that overlaps both the sender and receiver groups.
946  * \param[in] receivingGroup (MPI_Group *) Receiving group information.
947  * \param[in] rcompid (int*) External id of application that receives the mesh
948  * \param[in] method (int*) Partitioning ethod to use when sending the mesh;
949  * 0=trivial, 1=Zoltan Graph (PHG), 2=Zoltan Geometric (RCB).
950  * \return ErrCode The error code indicating success or failure.
951  */
952 ErrCode iMOAB_SendMesh( iMOAB_AppID pid,
953  MPI_Comm* joint_communicator,
954  MPI_Group* receivingGroup,
955  int* rcompid,
956  int* method );
957 
958 /**
959  * \brief Free up all of the buffers that were allocated when data transfer between
960  * components are performed. The nonblocking send and receive call buffers will be de-allocated
961  * once all the data is received by all involved tasks.
962  *
963  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID sender mesh.
964  * \param[in] context_id (int*) The context used for sending, to identify the communication graph.
965  * \return ErrCode The error code indicating success of failure.
966  */
967 ErrCode iMOAB_FreeSenderBuffers( iMOAB_AppID pid, int* context_d );
968 
969 /**
970  * \brief Migrate (receive) a set of elements from a sender group of tasks
971  *
972  * \note <B>Operations:</B> Collective on receiver group
973  *
974  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID mesh (receiver).
975  * \param[in] joint_communicator (MPI_Comm*) The joint communicator that overlaps both groups.
976  * \param[in] sending_group (MPI_Group *) The group of processes that are sending the mesh.
977  * \param[in] sender_comp_id ( int *) The unique application identifier that is sending the mesh
978  * \return ErrCode The error code indicating success or failure.
979  */
980 ErrCode iMOAB_ReceiveMesh( iMOAB_AppID pid,
981  MPI_Comm* joint_communicator,
982  MPI_Group* sending_group,
983  int* sender_comp_id );
984 
985 /**
986  * \brief migrate (send) a list of tags, from a sender group of tasks to a receiver group of tasks
987  *
988  * \note <B>Operations:</B> Collective over the sender group, nonblocking sends
989  *
990  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID of sender mesh.
991  * \param[in] tag_storage_name (const iMOAB_String) The name of the tags to be sent between the processes.
992  * Generally multiple tag names are concatenated, separated by ";".
993  * \param[in] joint_communicator (MPI_Comm) The joint communicator that overlaps both groups.
994  * \param[in] context_id (int*) The identifier for the other participating component in the
995  * intersection context (typically target); -1 if this refers to
996  * the original migration of meshes (internal detail).
997  * \return ErrCode The error code indicating success or failure.
998  */
999 ErrCode iMOAB_SendElementTag( iMOAB_AppID pid,
1000  const iMOAB_String tag_storage_name,
1001  MPI_Comm* joint_communicator,
1002  int* context_id );
1003 
1004 /**
1005  * \brief migrate (receive) a list of tags, from a sender group of tasks to a receiver group of tasks
1006  *
1007  * \note <B>Operations:</B> Collective over the receiver group, blocking receives
1008  *
1009  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID of receiver mesh.
1010  * \param[in] tag_storage_name (const iMOAB_String) The name of the tags to be sent between the processes.
1011  * Generally multiple tag names are concatenated, separated by ";".
1012  * \param[in] joint_communicator (MPI_Comm) The joint communicator that overlaps both groups.
1013  * \param[in] context_id (int*) The identifier for the other participating component in the
1014  * intersection context (typically target); -1 if this refers to
1015  * the original migration of meshes (internal detail).
1016  * \return ErrCode The error code indicating success or failure.
1017  */
1018 ErrCode iMOAB_ReceiveElementTag( iMOAB_AppID pid,
1019  const iMOAB_String tag_storage_name,
1020  MPI_Comm* joint_communicator,
1021  int* context_id );
1022 
1023 /**
1024  * \brief Compute a communication graph between 2 iMOAB applications, based on ID matching of key data.
1025  *
1026  * \note <B>Operations:</B> Collective
1027  *
1028  * \param[in] pid1 (iMOAB_AppID) The unique pointer to the first application ID.
1029  * \param[in] pid2 (iMOAB_AppID) The unique pointer to the second application ID.
1030  * \param[in] joint_communicator (MPI_Comm*) The MPI communicator that overlaps both groups.
1031  * \param[in] group1 (MPI_Group *) MPI group for first component.
1032  * \param[in] group2 (MPI_Group *) MPI group for second component.
1033  * \param[in] type1 (int *) The type of mesh used by pid1 (spectral with GLOBAL_DOFS, etc).
1034  * \param[in] type2 (int *) The type of mesh used by pid2 (point cloud with GLOBAL_ID, etc).
1035  * \param[in] comp1 (int*) The unique identifier of the first component.
1036  * \param[in] comp2 (int*) The unique identifier of the second component.
1037  * \return ErrCode The error code indicating success or failure.
1038  */
1039 ErrCode iMOAB_ComputeCommGraph( iMOAB_AppID pid1,
1040  iMOAB_AppID pid2,
1041  MPI_Comm* joint_communicator,
1042  MPI_Group* group1,
1043  MPI_Group* group2,
1044  int* type1,
1045  int* type2,
1046  int* comp1,
1047  int* comp2 );
1048 
1049 /**
1050  * \brief Recompute the communication graph between component and coupler, considering intersection coverage.
1051  *
1052  * \note Original communication graph for source used an initial partition, while during intersection some of the source
1053  * elements were sent to multiple tasks; send back the intersection coverage information for a direct communication
1054  * between source cx mesh on coupler tasks and source cc mesh on interested tasks on the component.
1055  * The intersection tasks will send to the original source component tasks, in a nonblocking way, the ids of all the
1056  * cells involved in intersection with the target cells. The new ParCommGraph between cc source mesh and cx source mesh
1057  * will be used just for tag migration, later on; The original ParCommGraph will stay unchanged, because this source mesh
1058  * could be used for other intersection (atm with lnd) ? on component source tasks, we will wait for information; from each
1059  * intersection task, will receive cells ids involved in intersection.
1060  *
1061  * \param[in] joint_communicator (MPI_Comm *) The joint communicator that overlaps component PEs and coupler PEs.
1062  * \param[in] pid_src (iMOAB_AppID) The unique application identifier for the component mesh on component PEs.
1063  * \param[in] pid_migr (iMOAB_AppID) The unique application identifier for the coupler mesh on coupler PEs.
1064  * \param[in] pid_intx (iMOAB_AppID) The unique application identifier representing the intersection context on coupler PEs.
1065  * \param[in] src_id (int*) The external id for the component mesh on component PE.
1066  * \param[in] migr_id (int*) The external id for the migrated mesh on coupler PEs.
1067  * \param[in] context_id (int*) The unique identifier of the other participating component in intersection (target).
1068  * \return ErrCode The error code indicating success or failure.
1069  */
1070 #ifdef MOAB_HAVE_TEMPESTREMAP
1071 /* CoverageGraph operates on the TempestRemapper covering set, so it requires TempestRemap. */
1072 ErrCode iMOAB_CoverageGraph( MPI_Comm* joint_communicator,
1073  iMOAB_AppID pid_src,
1074  iMOAB_AppID pid_migr,
1075  iMOAB_AppID pid_intx,
1076  int* src_id,
1077  int* migr_id,
1078  int* context_id );
1079 #endif /* #ifdef MOAB_HAVE_TEMPESTREMAP */
1080 
1081 /**
1082  * \brief Dump info about communication graph.
1083  *
1084  * \note <B>Operations:</B> Collective per sender or receiver group
1085  *
1086  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
1087  * \param[in] context_id (int*) The context_id names are separated by a semi-colon (";");
1088  * This is similar to the specifications in tag migration.
1089  * \param[in] is_sender (int*) Specify whether it is called from sender or receiver side.
1090  * \param[in] prefix (iMOAB_String) The prefix for file names in order to differentiate different stages.
1091  * \return ErrCode The error code indicating success or failure.
1092  */
1093 ErrCode iMOAB_DumpCommGraph( iMOAB_AppID pid, int* context_id, int* is_sender, const iMOAB_String prefix );
1094 
1095 /**
1096  * \brief merge vertices in an explicit, parallel mesh; it will also reassign global IDs on vertices,
1097  * and resolve parallel sharing of vertices.
1098  *
1099  * \note <B>Operations:</B> Collective
1100  *
1101  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
1102  * \return ErrCode The error code indicating success or failure.
1103  */
1104 ErrCode iMOAB_MergeVertices( iMOAB_AppID pid );
1105 
1106 #endif /* #ifdef MOAB_HAVE_MPI */
1107 
1108 #ifdef MOAB_HAVE_TEMPESTREMAP
1109 
1110 /**
1111  * @brief Set the number of ghost layers for the map.
1112  *
1113  * @param[in] pid (iMOAB_AppID) The unique pointer to the map application ID.
1114  * @param[in] n_src_ghost_layers (int*) The number of ghost layers for source.
1115  * @param[in] n_tgt_ghost_layers (int*) The number of ghost layers for target.
1116  * @return ErrCode The error code indicating success or failure.
1117  */
1118 ErrCode iMOAB_SetMapGhostLayers( iMOAB_AppID pid, int* n_src_ghost_layers, int* n_tgt_ghost_layers );
1119 
1120 /**
1121  * @brief Compute the source coverage mesh that completely encompasses the target surface mesh on a sphere.
1122  *
1123  * \note This step involves communication and mesh movement such that target mesh elements are within the
1124  * convex hull of the source mesh in the current task. The subsequent operations to compute the intersection
1125  * mesh between the coverage source and the target mesh are purely local.
1126  *
1127  * <B>Operations:</B> Collective on coupler tasks
1128  *
1129  * \param[in] pid_source (iMOAB_AppID) The unique pointer to the source application ID.
1130  * \param[in] pid_target (iMOAB_AppID) The unique pointer to the destination application ID.
1131  * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1132  * \return ErrCode The error code indicating success or failure.
1133  */
1134 ErrCode iMOAB_ComputeCoverageMesh( iMOAB_AppID pid_source, iMOAB_AppID pid_target, iMOAB_AppID pid_intersection );
1135 
1136 /**
1137  * \brief Write a MOAB source coverage mesh (maintained internally) along with the solution tags to a file.
1138  *
1139  * \note The iMOAB_WriteMesh function with appropriate parameters to write out the secondary file_set is used.
1140  *
1141  * <B>Operations:</B> Collective for parallel write, non collective for serial write.
1142  *
1143  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
1144  * \param[in] prefix (iMOAB_String) The MOAB mesh file (H5M) to write all the entities contained in the
1145  * coverage mesh set.
1146  * \return ErrCode The error code indicating success or failure.
1147  */
1148 ErrCode iMOAB_WriteCoverageMesh( iMOAB_AppID pid, const iMOAB_String prefix);
1149 
1150 /**
1151  * @brief Compute intersection of the surface meshes defined on a sphere. The resulting intersected mesh consists
1152  * of (convex) polygons with 1-1 associativity with both the source and destination meshes provided.
1153  *
1154  * \note The mesh intersection between two heterogeneous resolutions will be computed and stored in the fileset
1155  * corresponding to the \p pid_intersection application. This intersection data can be used to compute solution
1156  * projection weights between these meshes.
1157  *
1158  * <B>Operations:</B> Not collective. Embarassingly parallel.
1159  *
1160  * \param[in] pid_source (iMOAB_AppID) The unique pointer to the source application ID.
1161  * \param[in] pid_target (iMOAB_AppID) The unique pointer to the destination application ID.
1162  * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1163  * \return ErrCode The error code indicating success or failure.
1164  */
1165 ErrCode iMOAB_ComputeMeshIntersectionOnSphere( iMOAB_AppID pid_source,
1166  iMOAB_AppID pid_target,
1167  iMOAB_AppID pid_intersection );
1168 
1169 /**
1170  * \brief Compute the intersection of DoFs corresponding to surface meshes defined on a sphere. The resulting intersected
1171  * mesh essentially contains a communication pattern or a permutation matrix that couples both the source and destination
1172  * DoFs.
1173  *
1174  * \note <B>Operations:</B> Collective on coupler tasks
1175  *
1176  * \param[in] pid_source (iMOAB_AppID) The unique pointer to the source application ID.
1177  * \param[in] pid_target (iMOAB_AppID) The unique pointer to the destination application ID.
1178  * \param[out] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1179  * \return ErrCode The error code indicating success or failure.
1180  */
1181 ErrCode iMOAB_ComputePointDoFIntersection( iMOAB_AppID pid_source,
1182  iMOAB_AppID pid_target,
1183  iMOAB_AppID pid_intersection );
1184 
1185 #ifdef MOAB_HAVE_MPI
1186 
1187 /**
1188  * \brief Compute a communication graph between 2 moab apps, based on ID matching, between a component and map that
1189  * was read on coupler.
1190  *
1191  * \note Component can be target or source; also migrate meshes to coupler, from the components;
1192  * the mesh on coupler will be either source-like == coverage mesh or target-like the map is usually read
1193  * with rows fully distributed on tasks, so the target mesh will be a proper partition, while source mesh
1194  * coverage is dictated by the active columns on respective tasks.
1195  *
1196  * <B>Operations:</B> Collective
1197  *
1198  * \param[in] pid1 (iMOAB_AppID) The unique pointer to the first component.
1199  * \param[in] pid2 (iMOAB_AppID) The unique pointer to the map component.
1200  * \param[in] join (MPI_Comm) The joint communicator that overlaps both groups.
1201  * \param[in] group1 (MPI_Group *) The MPI group for the first component.
1202  * \param[in] group2 (MPI_Group *) The MPI group for the map component.
1203  * \param[in] type1 (int *) The type of mesh being migrated;
1204  * (1) spectral with GLOBAL_DOFS, (2) Point Cloud (3) FV cell.
1205  * \param[in] comp1 (int*) The universally unique identifier of first component.
1206  * \param[in] comp2 (int*) The universally unique identifier of map component.
1207  * \return ErrCode The error code indicating success or failure.
1208 */
1209 ErrCode iMOAB_MigrateMapMesh( iMOAB_AppID pid1,
1210  iMOAB_AppID pid2,
1211  MPI_Comm* join,
1212  MPI_Group* group1,
1213  MPI_Group* group2,
1214  int* type,
1215  int* comp1,
1216  int* comp2);
1217 
1218 #endif /* #ifdef MOAB_HAVE_MPI */
1219 
1220 /* Map (SCRIP weight-file) I/O supports either NetCDF or a PnetCDF fallback, so
1221  * expose the map-file API whenever any NC backend is available. */
1222 #if defined( MOAB_HAVE_NETCDF ) || defined( MOAB_HAVE_PNETCDF )
1223 
1224 /**
1225  * \brief Load the projection weights from disk to transfer a solution from a source surface mesh to a destination mesh defined on a sphere.
1226  * The intersection of the mesh should be computed a-priori.
1227  *
1228  * <B>Operations:</B> Collective
1229  *
1230  * \param[in] pid_source (iMOAB_AppID) The unique pointer to the source application ID.
1231  * \param[in] pid_target (iMOAB_AppID) The unique pointer to the destination application ID.
1232  * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1233  * \param[in] srctype (int *) type of mesh (1) spectral with GLOBAL_DOFS, (2) Point Cloud (3) FV cell
1234  * \param[in] tgttype (int *) type of mesh (1) spectral with GLOBAL_DOFS, (2) Point Cloud (3) FV cell
1235  * \param[in] arearead (int *) flag for reading (or not) area_a, area_b, or both possible values: 0, 1, 2, 3
1236  * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally.
1237  * Typically, values could be identifiers such as "scalar", "flux" or "custom".
1238  * \param[in] remap_weights_filename (iMOAB_String) The filename path to the mapping file to load in memory.
1239 */
1240 ErrCode iMOAB_LoadMapFile(
1241  iMOAB_AppID pid_source,
1242  iMOAB_AppID pid_target,
1243  iMOAB_AppID pid_intersection,
1244  int* srctype,
1245  int* tgttype,
1246  int* arearead,
1247  const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1248  const iMOAB_String remap_weights_filename );
1249 
1250 /**
1251  * \brief Write the projection weights to disk in order to transfer a solution from a source surface mesh to a destination
1252  * mesh defined on a sphere.
1253  *
1254  * \note <B>Operations:</B> Collective
1255  *
1256  * \param[in/out] pid_intersection (iMOAB_AppID) The unique pointer to the application ID to store the map.
1257  * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1258  * values could be identifiers such as "scalar", "flux" or "custom".
1259  * \param[in] remap_weights_filename (iMOAB_String) The filename path to the mapping file to load in memory.
1260  * \return ErrCode The error code indicating success or failure.
1261 */
1262 ErrCode iMOAB_WriteMapFile(
1263  iMOAB_AppID pid_intersection,
1264  const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1265  const iMOAB_String remap_weights_filename );
1266 
1267 #endif /* #if defined( MOAB_HAVE_NETCDF ) || defined( MOAB_HAVE_PNETCDF ) */
1268 
1269 /**
1270  * \brief Compute the projection weights to transfer a solution from a source surface mesh to a destination mesh defined
1271  * on a sphere. The intersection of the mesh should be computed a-priori.
1272  *
1273  * \note
1274  * The mesh intersection data-structure is used along with conservative remapping techniques in TempestRemap to compute
1275  * the projection weights for transferring the tag (\p soln_tag_name) from \p pid_src to \p pid_target applications.
1276  *
1277  * <B>Operations:</B> Collective
1278  *
1279  * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1280  * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1281  * values could be identifiers such as "scalar", "flux" or "custom".
1282  * \param[in] disc_method_source (iMOAB_String) The discretization type ("fv", "cgll", "dgll") for the solution field on the source grid.
1283  * \param[in] disc_order_source (int *) The discretization order for the solution field on the source grid.
1284  * \param[in] disc_method_target (iMOAB_String) The discretization type ("fv", "cgll", "dgll") for the solution field on the source grid.
1285  * \param[in] disc_order_target (int *) The discretization order for the solution field on the source grid.
1286  * \param[in] fNoBubble (int *) The flag to indicate whether to use bubbles in the interior of SE nodes.
1287  * Default: true i.e., no bubbles used.
1288  * \param[in] fMonotoneTypeID (int *) The flag to indicate whether solution monotonicity is to be preserved. 0: none, 1: mono.
1289  * \param[in] fVolumetric (int *) The flag to indicate whether we need to compute volumetric projection weights.
1290  * \param[in] fNoConservation (int *) The flag to indicate whether to ignore conservation of solution field during projection.
1291  * \param[in] fValidate (int *) The flag to indicate whether to validate the consistency and conservation of solution field during projection;
1292  * Production runs should not have this flag enabled to minimize collective operations.
1293  * \param[in] source_solution_tag_dof_name (iMOAB_String) The global DoF IDs corresponding to participating degrees-of-freedom for the source discretization.
1294  * \param[in] target_solution_tag_dof_name (iMOAB_String) The global DoF IDs corresponding to participating degrees-of-freedom for the target discretization.
1295  * \return ErrCode The error code indicating success or failure.
1296 */
1297 ErrCode iMOAB_ComputeScalarProjectionWeights(
1298  iMOAB_AppID pid_intersection,
1299  const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1300  const iMOAB_String disc_method_source,
1301  int* disc_order_source,
1302  const iMOAB_String disc_method_target,
1303  int* disc_order_target,
1304  const iMOAB_String fv_method,
1305  int* fNoBubble,
1306  int* fMonotoneTypeID,
1307  int* fVolumetric,
1308  int* fInverseDistanceMap,
1309  int* fNoConservation,
1310  int* fValidate,
1311  const iMOAB_String source_solution_tag_dof_name,
1312  const iMOAB_String target_solution_tag_dof_name );
1313 
1314 /**
1315  * \brief Apply the projection weights matrix operator onto the source tag in order to compute the solution (tag)
1316  * represented on the target grid. This operation can be understood as the application of a matrix vector product
1317  * (Y=P*X).
1318  *
1319  * \note <B>Operations:</B> Collective
1320  *
1321  * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1322  * \param[in] filter_type (int) Value specifying whether to use a nonlinear filter for property preservation.
1323  default (none) = 0, global = 1, local = 2, patch = 3
1324  * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1325  * values could be identifiers such as "scalar", "flux" or "custom".
1326  * \param[in] source_solution_tag_name (iMOAB_String) list of tag names corresponding to participating degrees-of-freedom for the source discretization;
1327  * names are separated by ";", the same way as for tag migration.
1328  * \param[in] target_solution_tag_name (iMOAB_String) list of tag names corresponding to participating degrees-of-freedom for the target discretization;
1329  * names are separated by ";", the same way as for tag migration.
1330  * \param[in] lo_weights_identifier (iMOAB_String) Optional. When non-NULL, identifies a low-order weight map whose stencil is used to
1331  * compute per-target-row bounds from the source data. The CAAS filter then preserves
1332  * these bounds on the high-order projection result. This implements the dual-map
1333  * nonlinear remapping algorithm (Clip-And-Assert-Sum).
1334  * \return ErrCode The error code indicating success or failure.
1335 */
1336 ErrCode iMOAB_ApplyScalarProjectionWeights(
1337  iMOAB_AppID pid_intersection,
1338  int* filter_type, /* CAAS_NONE = 0, CAAS_GLOBAL = 1, CAAS_LOCAL = 2, CAAS_LOCAL_ADJACENT = 3 */
1339  const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1340  const iMOAB_String source_solution_tag_name,
1341  const iMOAB_String target_solution_tag_name );
1342 
1343 #endif /* #ifdef MOAB_HAVE_TEMPESTREMAP */
1344 
1345 #ifdef MOAB_HAVE_MPI
1346 
1347 /**
1348  * Helper functions for MPI type conversions between Fortran and C++
1349  */
1350 
1351 /**
1352  * \brief MOAB MPI helper function to convert from a C-based MPI_Comm object
1353  * to a Fortran compatible MPI_Fint (integer) value.
1354  *
1355  * \param comm Input MPI_Comm C-object pointer.
1356  * \return MPI_Fint Output Fortran integer representing the comm object.
1357  */
1358 inline MPI_Fint MOAB_MPI_Comm_c2f( MPI_Comm* comm )
1359 {
1360  return MPI_Comm_c2f( *comm );
1361 }
1362 
1363 /**
1364  * \brief MOAB MPI helper function to convert from a Fortran-based MPI_Fint (integer)
1365  * value to a C/C++ compatible MPI_Comm object.
1366  *
1367  * \param fgroup (MPI_Fint) Input Fortran integer representing the MPI_Comm object.
1368  * \return MPI_Comm* Output C/C++-compatible MPI_Comm object pointer.
1369  */
1370 inline MPI_Comm* MOAB_MPI_Comm_f2c( MPI_Fint fcomm )
1371 {
1372  MPI_Comm* ccomm;
1373  ccomm = (MPI_Comm*)( malloc( sizeof( MPI_Comm ) ) ); // memory leak ?!
1374  *ccomm = MPI_Comm_f2c( fcomm );
1375  if( *ccomm == MPI_COMM_NULL )
1376  {
1377  free( ccomm );
1378  IMOAB_THROW_ERROR( "The MPI_Comm conversion from Fortran to C failed.", NULL );
1379  }
1380  else
1381  return ccomm;
1382 }
1383 
1384 /**
1385  * \brief MOAB MPI helper functions to convert from a C-based MPI_Group object
1386  * to a Fortran compatible MPI_Fint (integer) value.
1387  *
1388  * \param group Input MPI_Comm C-object pointer.
1389  * \return MPI_Fint Output Fortran integer representing the comm object.
1390  */
1391 inline MPI_Fint MOAB_MPI_Group_c2f( MPI_Group* group )
1392 {
1393  return MPI_Group_c2f( *group );
1394 }
1395 
1396 /**
1397  * \brief MOAB MPI helper function to convert from a Fortran-based MPI_Fint (integer)
1398  * value to a C/C++ compatible MPI_Group object.
1399  *
1400  * \param fgroup (MPI_Fint) Input Fortran integer representing the MPIGroup object.
1401  * \return MPI_Group* Output C/C++-compatible MPI_Group object pointer.
1402  */
1403 inline MPI_Group* MOAB_MPI_Group_f2c( MPI_Fint fgroup )
1404 {
1405  MPI_Group* cgroup;
1406  cgroup = (MPI_Group*)( malloc( sizeof( MPI_Group ) ) ); // memory leak ?!
1407  *cgroup = MPI_Group_f2c( fgroup );
1408  if( *cgroup == MPI_GROUP_NULL )
1409  {
1410  free( cgroup );
1411  IMOAB_THROW_ERROR( "The MPI_Group conversion from Fortran to C failed.", NULL );
1412  }
1413  else
1414  return cgroup;
1415 }
1416 
1417 #endif /* #ifdef MOAB_HAVE_MPI */
1418 
1419 #ifdef __cplusplus
1420 }
1421 #endif /* #ifdef __cplusplus */
1422 
1423 #endif /* #ifndef IMOAB_H */