Mesh Oriented datABase  (version 5.5.1)
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 /**
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 mesh.
1061  *
1062  * @param[in] pid (iMOAB_AppID) The unique pointer to the application ID.
1063  * @param[in] nghost_layers (int*) The number of ghost layers to set.
1064  * @return ErrCode The error code indicating success or failure.
1065  */
1066 ErrCode iMOAB_SetGhostLayers( iMOAB_AppID pid, int* nghost_layers );
1067 
1068 #endif /* #ifdef MOAB_HAVE_MPI */
1069 
1070 #ifdef MOAB_HAVE_TEMPESTREMAP
1071 
1072 /**
1073  * @brief Compute intersection of the surface meshes defined on a sphere. The resulting intersected mesh consists
1074  * of (convex) polygons with 1-1 associativity with both the source and destination meshes provided.
1075  *
1076  * \note The mesh intersection between two heterogeneous resolutions will be computed and stored in the fileset
1077  * corresponding to the \p pid_intersection application. This intersection data can be used to compute solution
1078  * projection weights between these meshes.
1079  *
1080  * <B>Operations:</B> Collective on coupler tasks
1081  *
1082  * \param[in] pid_source (iMOAB_AppID) The unique pointer to the source application ID.
1083  * \param[in] pid_target (iMOAB_AppID) The unique pointer to the destination application ID.
1084  * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1085  * \return ErrCode The error code indicating success or failure.
1086  */
1087 ErrCode iMOAB_ComputeMeshIntersectionOnSphere( iMOAB_AppID pid_source,
1088  iMOAB_AppID pid_target,
1089  iMOAB_AppID pid_intersection );
1090 
1091 /**
1092  * \brief Compute the intersection of DoFs corresponding to surface meshes defined on a sphere. The resulting intersected
1093  * mesh essentially contains a communication pattern or a permutation matrix that couples both the source and destination
1094  * DoFs.
1095  *
1096  * \note <B>Operations:</B> Collective on coupler tasks
1097  *
1098  * \param[in] pid_source (iMOAB_AppID) The unique pointer to the source application ID.
1099  * \param[in] pid_target (iMOAB_AppID) The unique pointer to the destination application ID.
1100  * \param[out] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1101  * \return ErrCode The error code indicating success or failure.
1102  */
1103 ErrCode iMOAB_ComputePointDoFIntersection( iMOAB_AppID pid_source,
1104  iMOAB_AppID pid_target,
1105  iMOAB_AppID pid_intersection );
1106 
1107 #ifdef MOAB_HAVE_NETCDF
1108 
1109 #ifdef MOAB_HAVE_MPI
1110 
1111 /**
1112  * \brief Compute a communication graph between 2 moab apps, based on ID matching, between a component and map that
1113  * was read on coupler.
1114  *
1115  * \note Component can be target or source; also migrate meshes to coupler, from the components;
1116  * the mesh on coupler will be either source-like == coverage mesh or target-like the map is usually read
1117  * with rows fully distributed on tasks, so the target mesh will be a proper partition, while source mesh
1118  * coverage is dictated by the active columns on respective tasks.
1119  *
1120  * <B>Operations:</B> Collective
1121  *
1122  * \param[in] pid1 (iMOAB_AppID) The unique pointer to the first component.
1123  * \param[in] pid2 (iMOAB_AppID) The unique pointer to the second component.
1124  * \param[in] pid3 (iMOAB_AppID) The unique pointer to the coupler instance of the mesh (component 2).
1125  * \param[in] join (MPI_Comm) The joint communicator that overlaps both groups.
1126  * \param[in] group1 (MPI_Group *) The MPI group for the first component.
1127  * \param[in] group2 (MPI_Group *) The MPI group for the second component.
1128  * \param[in] type1 (int *) The type of mesh being migrated;
1129  * (1) spectral with GLOBAL_DOFS, (2) Point Cloud (3) FV cell.
1130  * \param[in] comp1 (int*) The universally unique identifier of first component.
1131  * \param[in] comp2 (int*) The universally unique identifier of second component.
1132  * \param[in] direction (int*) A parameter indicating direction of the mesh migration.
1133  * i.e., whether it is from source to coupler (1), or from coupler to target (2).
1134  * \return ErrCode The error code indicating success or failure.
1135 */
1136 ErrCode iMOAB_MigrateMapMesh( iMOAB_AppID pid1,
1137  iMOAB_AppID pid2,
1138  iMOAB_AppID pid3,
1139  MPI_Comm* join,
1140  MPI_Group* group1,
1141  MPI_Group* group2,
1142  int* type,
1143  int* comp1,
1144  int* comp2,
1145  int* direction );
1146 
1147 #endif /* #ifdef MOAB_HAVE_MPI */
1148 
1149 /**
1150  * \brief Load the projection weights from disk to transfer a solution from a source surface mesh to a destination mesh defined on a sphere.
1151  * The intersection of the mesh should be computed a-priori.
1152  *
1153  * <B>Operations:</B> Collective
1154  *
1155  * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the application ID to store the map
1156  * \param[in] pid_cpl (iMOAB_AppID) The unique pointer to coupler instance of component; (-1) for old load
1157  * \param[in] col_or_row (int *) The flag to indicate whether distribution is according to source (0) or target grid (1)
1158  * \param[in] type (int *) type of mesh (1) spectral with GLOBAL_DOFS, (2) Point Cloud (3) FV cell
1159  * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1160  * values could be identifiers such as "scalar", "flux" or "custom".
1161  * \param[in] remap_weights_filename (iMOAB_String) The filename path to the mapping file to load in memory.
1162 */
1163 ErrCode iMOAB_LoadMappingWeightsFromFile(
1164  iMOAB_AppID pid_intersection,
1165  iMOAB_AppID pid_cpl,
1166  int* col_or_row,
1167  int* type,
1168  const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1169  const iMOAB_String remap_weights_filename );
1170 
1171 /**
1172  * \brief Write the projection weights to disk in order to transfer a solution from a source surface mesh to a destination
1173  * mesh defined on a sphere.
1174  *
1175  * \note <B>Operations:</B> Collective
1176  *
1177  * \param[in/out] pid_intersection (iMOAB_AppID) The unique pointer to the application ID to store the map.
1178  * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1179  * values could be identifiers such as "scalar", "flux" or "custom".
1180  * \param[in] remap_weights_filename (iMOAB_String) The filename path to the mapping file to load in memory.
1181  * \return ErrCode The error code indicating success or failure.
1182 */
1183 ErrCode iMOAB_WriteMappingWeightsToFile(
1184  iMOAB_AppID pid_intersection,
1185  const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1186  const iMOAB_String remap_weights_filename );
1187 
1188 #endif /* #ifdef MOAB_HAVE_NETCDF */
1189 
1190 /**
1191  * \brief Compute the projection weights to transfer a solution from a source surface mesh to a destination mesh defined
1192  * on a sphere. The intersection of the mesh should be computed a-priori.
1193  *
1194  * \note
1195  * The mesh intersection data-structure is used along with conservative remapping techniques in TempestRemap to compute
1196  * the projection weights for transferring the tag (\p soln_tag_name) from \p pid_src to \p pid_target applications.
1197  *
1198  * <B>Operations:</B> Collective
1199  *
1200  * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1201  * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1202  * values could be identifiers such as "scalar", "flux" or "custom".
1203  * \param[in] disc_method_source (iMOAB_String) The discretization type ("fv", "cgll", "dgll") for the solution field on the source grid.
1204  * \param[in] disc_order_source (int *) The discretization order for the solution field on the source grid.
1205  * \param[in] disc_method_target (iMOAB_String) The discretization type ("fv", "cgll", "dgll") for the solution field on the source grid.
1206  * \param[in] disc_order_target (int *) The discretization order for the solution field on the source grid.
1207  * \param[in] fNoBubble (int *) The flag to indicate whether to use bubbles in the interior of SE nodes.
1208  * Default: true i.e., no bubbles used.
1209  * \param[in] fMonotoneTypeID (int *) The flag to indicate whether solution monotonicity is to be preserved. 0: none, 1: mono.
1210  * \param[in] fVolumetric (int *) The flag to indicate whether we need to compute volumetric projection weights.
1211  * \param[in] fNoConservation (int *) The flag to indicate whether to ignore conservation of solution field during projection.
1212  * \param[in] fValidate (int *) The flag to indicate whether to validate the consistency and conservation of solution field during projection;
1213  * Production runs should not have this flag enabled to minimize collective operations.
1214  * \param[in] source_solution_tag_dof_name (iMOAB_String) The global DoF IDs corresponding to participating degrees-of-freedom for the source discretization.
1215  * \param[in] target_solution_tag_dof_name (iMOAB_String) The global DoF IDs corresponding to participating degrees-of-freedom for the target discretization.
1216  * \return ErrCode The error code indicating success or failure.
1217 */
1218 ErrCode iMOAB_ComputeScalarProjectionWeights(
1219  iMOAB_AppID pid_intersection,
1220  const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1221  const iMOAB_String disc_method_source,
1222  int* disc_order_source,
1223  const iMOAB_String disc_method_target,
1224  int* disc_order_target,
1225  const iMOAB_String fv_method,
1226  int* fNoBubble,
1227  int* fMonotoneTypeID,
1228  int* fVolumetric,
1229  int* fInverseDistanceMap,
1230  int* fNoConservation,
1231  int* fValidate,
1232  const iMOAB_String source_solution_tag_dof_name,
1233  const iMOAB_String target_solution_tag_dof_name );
1234 
1235 /**
1236  * \brief Apply the projection weights matrix operator onto the source tag in order to compute the solution (tag)
1237  * represented on the target grid. This operation can be understood as the application of a matrix vector product
1238  * (Y=P*X).
1239  *
1240  * \note <B>Operations:</B> Collective
1241  *
1242  * \param[in] pid_intersection (iMOAB_AppID) The unique pointer to the intersection application ID.
1243  * \param[in] filter_type (int) Value specifying whether to use a nonlinear filter for property preservation.
1244  default (none) = 0, global = 1, local = 2, patch = 3
1245  * \param[in] solution_weights_identifier (iMOAB_String) The unique identifier used to store the computed projection weights locally. Typically,
1246  * values could be identifiers such as "scalar", "flux" or "custom".
1247  * \param[in] source_solution_tag_name (iMOAB_String) list of tag names corresponding to participating degrees-of-freedom for the source discretization;
1248  * names are separated by ";", the same way as for tag migration.
1249  * \param[in] target_solution_tag_name (iMOAB_String) list of tag names corresponding to participating degrees-of-freedom for the target discretization;
1250  * names are separated by ";", the same way as for tag migration.
1251  * \return ErrCode The error code indicating success or failure.
1252 */
1253 ErrCode iMOAB_ApplyScalarProjectionWeights(
1254  iMOAB_AppID pid_intersection,
1255  int* filter_type, /* CAAS_NONE = 0, CAAS_GLOBAL = 1, CAAS_LOCAL = 2, CAAS_LOCAL_ADJACENT = 3 */
1256  const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
1257  const iMOAB_String source_solution_tag_name,
1258  const iMOAB_String target_solution_tag_name );
1259 
1260 #endif /* #ifdef MOAB_HAVE_TEMPESTREMAP */
1261 
1262 #ifdef MOAB_HAVE_MPI
1263 
1264 /**
1265  * Helper functions for MPI type conversions between Fortran and C++
1266  */
1267 
1268 /**
1269  * \brief MOAB MPI helper function to convert from a C-based MPI_Comm object
1270  * to a Fortran compatible MPI_Fint (integer) value.
1271  *
1272  * \param comm Input MPI_Comm C-object pointer.
1273  * \return MPI_Fint Output Fortran integer representing the comm object.
1274  */
1275 inline MPI_Fint MOAB_MPI_Comm_c2f( MPI_Comm* comm )
1276 {
1277  return MPI_Comm_c2f( *comm );
1278 }
1279 
1280 /**
1281  * \brief MOAB MPI helper function to convert from a Fortran-based MPI_Fint (integer)
1282  * value to a C/C++ compatible MPI_Comm object.
1283  *
1284  * \param fgroup (MPI_Fint) Input Fortran integer representing the MPI_Comm object.
1285  * \return MPI_Comm* Output C/C++-compatible MPI_Comm object pointer.
1286  */
1287 inline MPI_Comm* MOAB_MPI_Comm_f2c( MPI_Fint fcomm )
1288 {
1289  MPI_Comm* ccomm;
1290  ccomm = (MPI_Comm*)( malloc( sizeof( MPI_Comm ) ) ); // memory leak ?!
1291  *ccomm = MPI_Comm_f2c( fcomm );
1292  if( *ccomm == MPI_COMM_NULL )
1293  {
1294  free( ccomm );
1295  IMOAB_THROW_ERROR( "The MPI_Comm conversion from Fortran to C failed.", NULL );
1296  }
1297  else
1298  return ccomm;
1299 }
1300 
1301 /**
1302  * \brief MOAB MPI helper functions to convert from a C-based MPI_Group object
1303  * to a Fortran compatible MPI_Fint (integer) value.
1304  *
1305  * \param group Input MPI_Comm C-object pointer.
1306  * \return MPI_Fint Output Fortran integer representing the comm object.
1307  */
1308 inline MPI_Fint MOAB_MPI_Group_c2f( MPI_Group* group )
1309 {
1310  return MPI_Group_c2f( *group );
1311 }
1312 
1313 /**
1314  * \brief MOAB MPI helper function to convert from a Fortran-based MPI_Fint (integer)
1315  * value to a C/C++ compatible MPI_Group object.
1316  *
1317  * \param fgroup (MPI_Fint) Input Fortran integer representing the MPIGroup object.
1318  * \return MPI_Group* Output C/C++-compatible MPI_Group object pointer.
1319  */
1320 inline MPI_Group* MOAB_MPI_Group_f2c( MPI_Fint fgroup )
1321 {
1322  MPI_Group* cgroup;
1323  cgroup = (MPI_Group*)( malloc( sizeof( MPI_Group ) ) ); // memory leak ?!
1324  *cgroup = MPI_Group_f2c( fgroup );
1325  if( *cgroup == MPI_GROUP_NULL )
1326  {
1327  free( cgroup );
1328  IMOAB_THROW_ERROR( "The MPI_Group conversion from Fortran to C failed.", NULL );
1329  }
1330  else
1331  return cgroup;
1332 }
1333 
1334 #endif /* #ifdef MOAB_HAVE_MPI */
1335 
1336 #ifdef __cplusplus
1337 }
1338 #endif /* #ifdef __cplusplus */
1339 
1340 #endif /* #ifndef IMOAB_H */