MOAB: Mesh Oriented datABase  (version 5.4.0)
iMOAB.h
Go to the documentation of this file.
00001 #ifndef IMOAB_H
00002 #define IMOAB_H
00003 /**
00004  * \file iMOAB.h
00005  * iMOAB: a language-agnostic, lightweight interface to MOAB.
00006  *
00007  * Supports usage from C/C++, Fortran (77/90/2003), Python.
00008  *
00009  * \remark 1) All data in the interface are exposed via POD-types.
00010  * \remark 2) Pass everything by reference, so we do not have to use %VAL()
00011  * \remark 3) Arrays are allocated by the user code. No concerns about
00012  *            de-allocation of the data will be taken up by the interface.
00013  * \remark 4) Always pass the pointer to the start of array along with the
00014  *            total allocated size for the array.
00015  * \remark 5) Return the filled array requested by user along with
00016  *            optionally the actual length of the array that was filled.
00017  *            (for typical cases, should be the allocated length)
00018  */
00019 
00020 /**
00021  * \Notes
00022  * 1) Fortran MPI_Comm won't work. Take an integer argument and use MPI_F2C calls to get the C-Comm object
00023  * 2) ReadHeaderInfo - Does it need the pid ?
00024  * 3) Reuse the comm object from the registration for both load and write operations.
00025  *    Do not take comm objects again to avoid confusion and retain consistency.
00026  * 4) Decipher the global comm object and the subset partioning for each application based on the comm object
00027  * 5) GetMeshInfo - return separately the owned and ghosted vertices/elements -- not together in visible_** but rather
00028  *    owned_** and ghosted_**. Make these arrays of size 2.
00029  * 6) Should we sort the vertices after ghosting, such that the locally owned is first, and the ghosted appended next.
00030  * 7) RCM only for the owned part of the mesh -- do not screw with the ghosted layers
00031  * 8) GetBlockID - identical to GetVertexID -- return the global numbering for block
00032  * 9) GetVertexID -- remember that the order of vertices returned have an implicit numbering embedded in it.
00033  *    DO NOT CHANGE THIS ORDERING...
00034  * 10) GetBlockInfo takes global Block ID; Remove blockname unless there is a separate use case for it..
00035  * 11) GetElementConnectivity - clarify whether we return global or local vertex numbering.
00036  *     Preferably local numbering else lot of deciphering for global.
00037  */
00038 #include "moab/MOABConfig.h"
00039 #include "moab/Types.hpp"
00040 
00041 #ifdef __cplusplus
00042 #include <cstdio>
00043 #include <cassert>
00044 #include <cstdlib>
00045 #else
00046 #include <stdio.h>
00047 #include <assert.h>
00048 #include <stdlib.h>
00049 #endif
00050 
00051 #define iMOAB_AppID    int*
00052 #define iMOAB_String   char*
00053 #define iMOAB_GlobalID int
00054 #define iMOAB_LocalID  int
00055 #ifdef __cplusplus
00056 #define ErrCode moab::ErrorCode
00057 #else
00058 #define ErrCode int
00059 #endif
00060 
00061 #ifdef _MSC_VER
00062 #define __PRETTY_FUNCTION__ __FUNCSIG__
00063 #else
00064 #if !defined( __cplusplus ) || !defined( __PRETTY_FUNCTION__ )
00065 #define __PRETTY_FUNCTION__ __func__
00066 #endif
00067 #endif
00068 
00069 /**
00070  * @brief MOAB tag types can be: dense/sparse, and of int/double/EntityHandle types.
00071  * They can also be defined on both elements and vertices of the mesh.
00072  */
00073 enum MOAB_TAG_TYPE
00074 {
00075     DENSE_INTEGER       = 0,
00076     DENSE_DOUBLE        = 1,
00077     DENSE_ENTITYHANDLE  = 2,
00078     SPARSE_INTEGER      = 3,
00079     SPARSE_DOUBLE       = 4,
00080     SPARSE_ENTITYHANDLE = 5
00081 };
00082 
00083 /**
00084  * @brief Define MOAB tag ownership information i.e., the entity where the tag is primarily defined
00085  * This is typically used to query the tag data and to set it back.
00086  */
00087 enum MOAB_TAG_OWNER_TYPE
00088 {
00089     TAG_VERTEX  = 0,
00090     TAG_EDGE    = 1,
00091     TAG_FACE    = 2,
00092     TAG_ELEMENT = 3
00093 };
00094 
00095 #define CHK_MPI_ERR( ierr )                          \
00096     {                                                \
00097         if( 0 != ( ierr ) ) return moab::MB_FAILURE; \
00098     }
00099 
00100 #define IMOAB_CHECKPOINTER( prmObj, position )                                                 \
00101     {                                                                                          \
00102         if( prmObj == nullptr )                                                                \
00103         {                                                                                      \
00104             printf( "InputParamError at %d: '%s' is invalid and null.\n", position, #prmObj ); \
00105             return moab::MB_UNHANDLED_OPTION;                                                  \
00106         }                                                                                      \
00107     }
00108 
00109 #define IMOAB_THROW_ERROR( message, retval )                                                                       \
00110     {                                                                                                              \
00111         printf( "iMOAB Error: %s.\n Location: %s in %s:%d.\n", message, __PRETTY_FUNCTION__, __FILE__, __LINE__ ); \
00112         return retval;                                                                                             \
00113     }
00114 
00115 #ifndef NDEBUG
00116 #define IMOAB_ASSERT_RET( condition, message, retval )                                                         \
00117     {                                                                                                          \
00118         if( !( condition ) )                                                                                   \
00119         {                                                                                                      \
00120             printf( "iMOAB Error: %s.\n Failed condition: %s\n Location: %s in %s:%d.\n", message, #condition, \
00121                     __PRETTY_FUNCTION__, __FILE__, __LINE__ );                                                 \
00122             return retval;                                                                                     \
00123         }                                                                                                      \
00124     }
00125 
00126 #define IMOAB_ASSERT( condition, message ) IMOAB_ASSERT_RET( condition, message, moab::MB_UNHANDLED_OPTION )
00127 
00128 #else
00129 #define IMOAB_ASSERT( condition, message )
00130 #define IMOAB_ASSERT_RET( condition, message, retval )
00131 #endif
00132 
00133 #ifdef __cplusplus
00134 extern "C" {
00135 #endif
00136 
00137 /**
00138  * \brief Initialize the iMOAB interface implementation.
00139  *
00140  * \note Will create the MOAB instance, if not created already (reference counted).
00141  *
00142  * <B>Operations:</B> Collective
00143  *
00144  * \param[in] argc (int)           Number of command line arguments
00145  * \param[in] argv (iMOAB_String*) Command line arguments
00146  * @return ErrCode
00147  */
00148 ErrCode iMOAB_Initialize( int argc, iMOAB_String* argv );
00149 
00150 /**
00151  * \brief Initialize the iMOAB interface implementation from Fortran driver.
00152  *
00153  * It will create the MOAB instance, if not created already (reference counted).
00154  *
00155  * <B>Operations:</B> Collective
00156  *
00157  * \return ErrCode    The error code indicating success or failure.
00158  */
00159 ErrCode iMOAB_InitializeFortran();
00160 
00161 /**
00162  * \brief Finalize the iMOAB interface implementation.
00163  *
00164  * It will delete the internally reference counted MOAB instance, if the reference count reaches 0.
00165  *
00166  * <B>Operations:</B> Collective
00167  *
00168  * \return ErrCode    The error code indicating success or failure.
00169  */
00170 ErrCode iMOAB_Finalize();
00171 
00172 /**
00173  * \brief Register application - Create a unique application ID and bootstrap interfaces for further queries.
00174  *
00175  * \note
00176  * Internally, a mesh set will be associated with the application ID and all subsequent queries on the MOAB
00177  * instance will be directed to this mesh/file set.
00178  *
00179  * <B>Operations:</B> Collective
00180  *
00181  * \param[in]  app_name (iMOAB_String) Application name (PROTEUS, NEK5000, etc)
00182  * \param[in]  comm (MPI_Comm*)        MPI communicator to be used for all mesh-related queries originating
00183  *                                     from this application
00184  * \param[in]  compid (int*)           The unique external component identifier
00185  * \param[out] pid (iMOAB_AppID)       The unique pointer to the application ID
00186  * \return ErrCode                     The error code indicating success or failure.
00187  */
00188 ErrCode iMOAB_RegisterApplication( const iMOAB_String app_name,
00189 #ifdef MOAB_HAVE_MPI
00190                                    MPI_Comm* comm,
00191 #endif
00192                                    int* compid,
00193                                    iMOAB_AppID pid );
00194 
00195 /**
00196  * \brief De-Register application: delete mesh (set) associated with the application ID.
00197  *
00198  * \note The associated communicator will be released, and all associated mesh entities and sets will be deleted from the
00199  * mesh data structure. Associated tag storage data will be freed too.
00200  *
00201  * <B>Operations:</B> Collective
00202  *
00203  * \param[in] pid (iMOAB_AppID) The unique pointer to the application ID
00204  * \return ErrCode                     The error code indicating success or failure.
00205  */
00206 ErrCode iMOAB_DeregisterApplication( iMOAB_AppID pid );
00207 
00208 /**
00209  * \brief Register a Fortran-based application - Create a unique application ID and bootstrap interfaces
00210  * for further queries.
00211  *
00212  * \note
00213  * Internally, the comm object, usually a 32 bit integer in Fortran, will be converted using MPI_Comm_f2c and stored as
00214  * MPI_Comm. A mesh set will be associated with the application ID and all subsequent queries on the MOAB instance will
00215  * be directed to this mesh/file set.
00216  *
00217  * <B>Operations:</B> Collective
00218  *
00219  * \param[in]  app_name (iMOAB_String) Application name ("MySolver", "E3SM", "DMMoab", "PROTEUS", "NEK5000", etc)
00220  * \param[in]  communicator (int*)     Fortran MPI communicator to be used for all mesh-related queries originating from this application.
00221  * \param[in]  compid (int*)           External component id, (A *const* unique identifier).
00222  * \param[out] pid (iMOAB_AppID)       The unique pointer to the application ID.
00223  * \return ErrCode                     The error code indicating success or failure.
00224  */
00225 ErrCode iMOAB_RegisterApplicationFortran( const iMOAB_String app_name,
00226 #ifdef MOAB_HAVE_MPI
00227                                           int* communicator,
00228 #endif
00229                                           int* compid,
00230                                           iMOAB_AppID pid );
00231 
00232 /**
00233  * \brief De-Register the Fortran based application: delete mesh (set) associated with the application ID.
00234  *
00235  * \note The associated communicator will be released, and all associated mesh entities and sets will be
00236  * deleted from the mesh data structure. Associated tag storage data will be freed too.
00237  *
00238  * <B>Operations:</B> Collective
00239  *
00240  * \param[in] pid (iMOAB_AppID)   The unique pointer to the application ID
00241  * \return ErrCode                The error code indicating success or failure.
00242  */
00243 ErrCode iMOAB_DeregisterApplicationFortran( iMOAB_AppID pid );
00244 
00245 /**
00246  * \brief It should be called on master task only, and information obtained could be broadcasted by the user.
00247  * It is a fast lookup in the header of the file.
00248  *
00249  * \note
00250  * <B>Operations:</B> Not collective
00251  *
00252  * \param[in]  filename (iMOAB_String)    The MOAB mesh file (H5M) to probe for header information.
00253  * \param[out] num_global_vertices (int*) The total number of vertices in the mesh file.
00254  * \param[out] num_global_elements (int*) The total number of elements (of highest dimension only).
00255  * \param[out] num_dimension (int*)       The highest dimension of elements in the mesh
00256  *                                        (Edge=1, Tri/Quad=2, Tet/Hex/Prism/Pyramid=3).
00257  * \param[out] num_parts (int*)           The total number of partitions available in the mesh file, typically
00258  *                                        partitioned with mbpart during pre-processing.
00259  * \return ErrCode                        The error code indicating success or failure.
00260  */
00261 ErrCode iMOAB_ReadHeaderInfo( const iMOAB_String filename,
00262                               int* num_global_vertices,
00263                               int* num_global_elements,
00264                               int* num_dimension,
00265                               int* num_parts );
00266 
00267 /**
00268  * \brief Load a MOAB mesh file in parallel and exchange ghost layers as requested.
00269  *
00270  * \note All communication is MPI-based, and read options include parallel loading information, resolving
00271  * shared entities. Local MOAB instance is populated with mesh cells and vertices in the corresponding
00272  * local partitions.
00273  *
00274  * This will also exchange ghost cells and vertices, as requested. The default bridge dimension is 0 (vertices),
00275  * and all additional lower dimensional sub-entities are exchanged (mesh edges and faces). The tags in the file are not
00276  * exchanged by default. Default tag information for GLOBAL_ID, MATERIAL_SET, NEUMANN_SET and DIRICHLET_SET is
00277  * exchanged. Global ID tag is exchanged for all cells and vertices. Material sets, Neumann sets and Dirichlet sets
00278  * are all augmented with the ghost entities.
00279  *
00280  * <B>Operations:</B> Collective
00281  *
00282  * \param[in] pid (iMOAB_AppID)            The unique pointer to the application ID.
00283  * \param[in] filename (iMOAB_String)      The MOAB mesh file (H5M) to load onto the internal application mesh set.
00284  * \param[in] read_options (iMOAB_String)  Additional options for reading the MOAB mesh file in parallel.
00285  * \param[in] num_ghost_layers (int*)      The total number of ghost layers to exchange during mesh loading.
00286  * \return ErrCode                         The error code indicating success or failure.
00287  */
00288 ErrCode iMOAB_LoadMesh( iMOAB_AppID pid,
00289                         const iMOAB_String filename,
00290                         const iMOAB_String read_options,
00291                         int* num_ghost_layers );
00292 
00293 /**
00294  * \brief Create vertices for an app; it assumes no other vertices
00295  *
00296  * \note <B>Operations:</B> Not collective
00297  *
00298  * \param[in]  pid (iMOAB_AppID)           The unique pointer to the application ID.
00299  * \param[in]  coords_len (int*)           Size of the \p coordinates array (nverts * dim).
00300  * \param[in]  dim (int*)                  Dimension of the vertex coordinates (usually 3).
00301  * \param[in]  coordinates (double*)       Coordinates of all vertices, interleaved.
00302  * \return ErrCode                         The error code indicating success or failure.
00303  */
00304 ErrCode iMOAB_CreateVertices( iMOAB_AppID pid, int* coords_len, int* dim, double* coordinates );
00305 
00306 /**
00307  * \brief Create elements for an app; it assumes connectivity from local vertices, in order
00308  *
00309  * \note <B>Operations:</B> Not collective
00310  *
00311  * \param[in]  pid (iMOAB_AppID)               The unique pointer to the application ID.
00312  * \param[in]  num_elem (int*)                 Number of elements.
00313  * \param[in]  type (int*)                     Type of element (moab type).
00314  * \param[in]  num_nodes_per_element (int*)    Number of nodes per element.
00315  * \param[in]  connectivity (int *)            Connectivity array, with respect to vertices (assumed contiguous).
00316  * \param[in]  block_ID (int *)                The local block identifier, which will now contain the elements.
00317  * \return ErrCode                             The error code indicating success or failure.
00318  */
00319 ErrCode iMOAB_CreateElements( iMOAB_AppID pid,
00320                               int* num_elem,
00321                               int* type,
00322                               int* num_nodes_per_element,
00323                               int* connectivity,
00324                               int* block_ID );
00325 
00326 /**
00327  * \brief Resolve shared entities using global markers on shared vertices.
00328  *
00329  * \note  Global markers can be a global node id, for example, or a global DoF number (as for HOMME)
00330  *
00331  * <B>Operations:</B> Collective .
00332  *
00333  * \param[in] pid (iMOAB_AppID)            The unique pointer to the application ID.
00334  * \param[in] num_verts (int*)             Number of vertices.
00335  * \param[in] marker (int*)                Resolving marker (global id marker).
00336  * \return ErrCode                         The error code indicating success or failure.
00337  */
00338 ErrCode iMOAB_ResolveSharedEntities( iMOAB_AppID pid, int* num_verts, int* marker );
00339 
00340 /**
00341  * \brief Create the requested number of ghost layers for the parallel mesh.
00342  *
00343  * \note The routine assumes that the shared entities were resolved successfully, and that
00344  * the mesh is properly distributed on separate tasks.
00345  *
00346  * <B>Operations:</B> Collective.
00347  *
00348  * \param[in] pid (iMOAB_AppID)            The unique pointer to the application ID.
00349  * \param[in] ghost_dim (int*)             Desired ghost dimension (2 or 3, most of the time).
00350  * \param[in] num_ghost_layers (int*)      Number of ghost layers requested.
00351  * \param[in] bridge_dim (int*)            Bridge dimension (0 for vertices, 1 for edges, 2 for faces).
00352  * \return ErrCode                         The error code indicating success or failure.
00353  */
00354 ErrCode iMOAB_DetermineGhostEntities( iMOAB_AppID pid, int* ghost_dim, int* num_ghost_layers, int* bridge_dim );
00355 
00356 /**
00357  * \brief Write a MOAB mesh along with the solution tags to a file.
00358  *
00359  * \note The interface will write one single file (H5M) and for serial files (VTK/Exodus), it will write one
00360  * file per task. Write options include parallel write options, if needed. Only the mesh set and solution data
00361  * associated to the application will be written to the file.
00362  *
00363  * <B>Operations:</B> Collective for parallel write, non collective for serial write.
00364  *
00365  * \param[in] pid (iMOAB_AppID)            The unique pointer to the application ID.
00366  * \param[in] filename (iMOAB_String)      The MOAB mesh file (H5M) to write all the entities contained in the
00367  *                                         internal application mesh set.
00368  * \param[in] write_options (iMOAB_String) Additional options for writing the MOAB mesh in parallel.
00369  * \return ErrCode                         The error code indicating success or failure.
00370  */
00371 ErrCode iMOAB_WriteMesh( iMOAB_AppID pid, const iMOAB_String filename, const iMOAB_String write_options );
00372 
00373 /**
00374  * \brief Write a local MOAB mesh copy.
00375  *
00376  * \note The interface will write one file per task. Only the local mesh set and solution data associated
00377  * to the application will be written to the file. Very convenient method used for debugging.
00378  *
00379  * <B>Operations:</B> Not Collective (independent operation).
00380  *
00381  * \param[in] pid (iMOAB_AppID)       The unique pointer to the application ID.
00382  * \param[in] prefix (iMOAB_String)   The MOAB file prefix that will be used with task ID in parallel.
00383  * \return ErrCode                    The error code indicating success or failure.
00384  */
00385 ErrCode iMOAB_WriteLocalMesh( iMOAB_AppID pid, iMOAB_String prefix );
00386 
00387 /**
00388  * \brief Update local mesh data structure, from file information.
00389  *
00390  * \note The method should be called after mesh modifications, for example reading a file or creating mesh in memory
00391  *
00392  * <B>Operations:</B> Not Collective
00393  *
00394  * \param[in]  pid (iMOAB_AppID)       The unique pointer to the application ID.
00395  * \return ErrCode                     The error code indicating success or failure.
00396  */
00397 ErrCode iMOAB_UpdateMeshInfo( iMOAB_AppID pid );
00398 
00399 /**
00400  * \brief Retrieve all the important mesh information related to vertices, elements, vertex and surface boundary conditions.
00401  *
00402  * \note Number of visible vertices and cells include ghost entities. All arrays returned have size 3.
00403  * Local entities are first, then ghost entities are next. Shared vertices can be owned in MOAB sense by
00404  * different tasks. Ghost vertices and cells are always owned by other tasks.
00405  *
00406  * <B>Operations:</B> Not Collective
00407  *
00408  * \param[in]  pid (iMOAB_AppID)            The unique pointer to the application ID.
00409  * \param[out] num_visible_vertices (int*)  The number of vertices in the current partition/process arranged.
00410  *                                          as: owned/shared only, ghosted, total_visible (array allocated by
00411  *                                          user, <TT>size := 3</TT>).
00412  * \param[out] num_visible_elements (int*)  The number of elements in current partition/process arranged as: owned only,
00413  *                                          ghosted/shared, total_visible (array allocated by user, <TT>size := 3</TT>).
00414  * \param[out] num_visible_blocks (int*)    The number of material sets in local mesh in current partition/process
00415  *                                          arranged as: owned only, ghosted/shared, total_visible (array allocated by
00416  *                                          user, <TT>size := 3</TT>).
00417  * \param[out] num_visible_surfaceBC (int*) The number of mesh surfaces that have a NEUMANN_SET BC defined in local mesh
00418  *                                          in current partition/process arranged as: owned only, ghosted/shared,
00419  *                                          total_visible (array allocated by user, <TT>size := 3</TT>).
00420  * \param[out] num_visible_vertexBC (int*)  The number of vertices that have a DIRICHLET_SET BC defined in local mesh in
00421  *                                          current partition/process arranged as: owned only, ghosted/shared,
00422  *                                          total_visible (array allocated by user, <TT>size := 3</TT>).
00423  * \return ErrCode                          The error code indicating success or failure.
00424  */
00425 ErrCode iMOAB_GetMeshInfo( iMOAB_AppID pid,
00426                            int* num_visible_vertices,
00427                            int* num_visible_elements,
00428                            int* num_visible_blocks,
00429                            int* num_visible_surfaceBC,
00430                            int* num_visible_vertexBC );
00431 
00432 /**
00433  * \brief Get the global vertex IDs for all locally visible (owned and shared/ghosted) vertices.
00434  *
00435  * \note The array should be allocated by the user, sized with the total number of visible vertices
00436  * from iMOAB_GetMeshInfo method.
00437  *
00438  * <B>Operations:</B> Not collective
00439  *
00440  * \param[in]  pid (iMOAB_AppID)                   The unique pointer to the application ID.
00441  * \param[in]  vertices_length (int*)              The allocated size of array
00442  *                                                 (typical <TT>size := num_visible_vertices</TT>).
00443  * \param[out] global_vertex_ID (iMOAB_GlobalID*)  The global IDs for all locally visible
00444  *                                                 vertices (array allocated by user).
00445  * \return ErrCode                                 The error code indicating success or failure.
00446  */
00447 ErrCode iMOAB_GetVertexID( iMOAB_AppID pid, int* vertices_length, iMOAB_GlobalID* global_vertex_ID );
00448 
00449 /**
00450  * \brief Get vertex ownership information.
00451  *
00452  * For each vertex based on the local ID, return the process that owns the vertex (local, shared or ghost)
00453  *
00454  * \note Shared vertices could be owned by different tasks. Local and shared vertices are first, ghost
00455  * vertices are next in the array. Ghost vertices are always owned by a different process ID. Array allocated
00456  * by the user with total size of visible vertices.
00457  *
00458  * <B>Operations:</B> Not Collective
00459  *
00460  * \param[in]  pid (iMOAB_AppID)             The unique pointer to the application ID.
00461  * \param[in]  vertices_length (int*)        The allocated size of array
00462  *                                           (typically <TT>size := num_visible_vertices</TT>).
00463  * \param[out] visible_global_rank_ID (int*) The processor rank owning each of the local vertices.
00464  * \return ErrCode                           The error code indicating success or failure.
00465  */
00466 ErrCode iMOAB_GetVertexOwnership( iMOAB_AppID pid, int* vertices_length, int* visible_global_rank_ID );
00467 
00468 /**
00469  * \brief Get vertex coordinates for all local (owned and ghosted) vertices.
00470  *
00471  * \note coordinates are returned in an array allocated by user, interleaved. (do need an option for blocked
00472  * coordinates ?) size of the array is dimension times number of visible vertices. The local ordering is implicit,
00473  * owned/shared vertices are first, then ghosts.
00474  *
00475  * <B>Operations:</B> Not Collective
00476  *
00477  * \param[in]  pid (iMOAB_AppID)     The unique pointer to the application ID.
00478  * \param[in]  coords_length (int*)  The size of the allocated coordinate array (array allocated by
00479  *                                   user, <TT>size := 3*num_visible_vertices</TT>).
00480  * \param[out] coordinates (double*) The pointer to user allocated memory that will be filled with
00481  *                                   interleaved coordinates.
00482  * \return ErrCode                   The error code indicating success or failure.
00483  */
00484 ErrCode iMOAB_GetVisibleVerticesCoordinates( iMOAB_AppID pid, int* coords_length, double* coordinates );
00485 
00486 /**
00487  * \brief Get the global block IDs for all locally visible (owned and shared/ghosted) blocks.
00488  *
00489  * \note Block IDs are corresponding to MATERIAL_SET tags for material sets. Usually the block ID is exported
00490  * from Cubit as a unique integer value. First blocks are local, and next blocks are fully ghosted. First blocks
00491  * have at least one owned cell/element, ghost blocks have only ghost cells. Internally, a block corresponds to a
00492  * mesh set with a MATERIAL_SET tag value equal to the block ID.
00493  *
00494  * <B>Operations:</B> Not Collective
00495  *
00496  * \param[in]  pid (iMOAB_AppID)                  The unique pointer to the application ID.
00497  * \param[in]  block_length (int*)                The allocated size of array
00498  *                                                (typical <TT>size := num_visible_blocks</TT>).
00499  * \param[out] global_block_IDs (iMOAB_GlobalID*) The global IDs for all locally visible blocks
00500  *                                                (array allocated by user).
00501  * \return ErrCode                                The error code indicating success or failure.
00502  */
00503 ErrCode iMOAB_GetBlockID( iMOAB_AppID pid, int* block_length, iMOAB_GlobalID* global_block_IDs );
00504 
00505 /**
00506  * \brief Get the global block information and number of visible elements of belonging to a
00507  * block (MATERIAL SET).
00508  *
00509  * \note A block has to be homogeneous, it can contain elements of a single type.
00510  *
00511  * <B>Operations:</B> Not Collective
00512  *
00513  * \param[in]  pid (iMOAB_AppID)                 The unique pointer to the application ID.
00514  * \param[in]  global_block_ID (iMOAB_GlobalID)  The global block ID of the set to be queried.
00515  * \param[out] vertices_per_element (int*)       The number of vertices per element.
00516  * \param[out] num_elements_in_block (int*)      The number of elements in block.
00517  * \return ErrCode                               The error code indicating success or failure.
00518  */
00519 ErrCode iMOAB_GetBlockInfo( iMOAB_AppID pid,
00520                             iMOAB_GlobalID* global_block_ID,
00521                             int* vertices_per_element,
00522                             int* num_elements_in_block );
00523 
00524 /**
00525  * \brief Get the visible elements information.
00526  *
00527  * Return for all visible elements the global IDs, ranks they belong to, block ids they belong to.
00528  *
00529  * \todo : Can we also return the index for each block ID?
00530  *
00531  * \note <B>Operations:</B> Not Collective
00532  *
00533  * \param[in]  pid (iMOAB_AppID)                     The unique pointer to the application ID.
00534  * \param[in]  num_visible_elements (int*)           The number of visible elements (returned by \c GetMeshInfo).
00535  * \param[out] element_global_IDs (iMOAB_GlobalID*)  Element global ids to be added to the block.
00536  * \param[out] ranks (int*)                          The owning ranks of elements.
00537  * \param[out] block_IDs (iMOAB_GlobalID*)           The block ids containing the elements.
00538  * \return ErrCode                                   The error code indicating success or failure.
00539  */
00540 ErrCode iMOAB_GetVisibleElementsInfo( iMOAB_AppID pid,
00541                                       int* num_visible_elements,
00542                                       iMOAB_GlobalID* element_global_IDs,
00543                                       int* ranks,
00544                                       iMOAB_GlobalID* block_IDs );
00545 
00546 /**
00547  * \brief Get the connectivities for elements contained within a certain block.
00548  *
00549  * \note input is the block ID. Should we change to visible block local index?
00550  *
00551  * <B>Operations:</B> Not Collective
00552  *
00553  * \param[in]  pid (iMOAB_AppID)                 The unique pointer to the application ID.
00554  * \param[in]  global_block_ID (iMOAB_GlobalID*) The global block ID of the set being queried.
00555  * \param[in]  connectivity_length (int*)        The allocated size of array.
00556  *                                               (typical <TT>size := vertices_per_element*num_elements_in_block</TT>)
00557  * \param[out] element_connectivity (int*)       The connectivity array to store element ordering in MOAB canonical
00558  *                                               numbering scheme (array allocated by user); array contains vertex
00559  *                                               indices in the local numbering order for vertices elements are in
00560  *                                               the same order as provided by GetElementOwnership and GetElementID.
00561  * \return ErrCode                               The error code indicating success or failure.
00562  */
00563 ErrCode iMOAB_GetBlockElementConnectivities( iMOAB_AppID pid,
00564                                              iMOAB_GlobalID* global_block_ID,
00565                                              int* connectivity_length,
00566                                              int* element_connectivity );
00567 
00568 /**
00569  * \brief Get the connectivity for one element only.
00570  *
00571  * \note This is a convenience method and in general should not be used unless necessary.
00572  * You should use colaesced calls for multiple elements for efficiency.
00573  *
00574  * <B>Operations:</B> Not Collective
00575  *
00576  * \param[in]  pid (iMOAB_AppID)                 The unique pointer to the application ID.
00577  * \param[in]  elem_index (iMOAB_LocalID *)      Local element index.
00578  * \param[in,out] connectivity_length (int *)    On input, maximum length of connectivity. On output, actual length.
00579  * \param[out] element_connectivity (int*)       The connectivity array to store connectivity in MOAB canonical numbering
00580  *                                               scheme. Array contains vertex indices in the local numbering order for
00581  *                                               vertices.
00582  * \return ErrCode                               The error code indicating success or failure.
00583  */
00584 ErrCode iMOAB_GetElementConnectivity( iMOAB_AppID pid,
00585                                       iMOAB_LocalID* elem_index,
00586                                       int* connectivity_length,
00587                                       int* element_connectivity );
00588 
00589 /**
00590  * \brief Get the element ownership within a certain block i.e., processor ID of the element owner.
00591  *
00592  * \note : Should we use local block index for input, instead of the global block ID ?
00593  *
00594  * <B>Operations:</B> Not Collective
00595  *
00596  * \param[in]  pid (iMOAB_AppID)                 The unique pointer to the application ID.
00597  * \param[in]  global_block_ID (iMOAB_GlobalID)  The global block ID of the set being queried.
00598  * \param[in]  num_elements_in_block (int*)      The allocated size of ownership array, same as
00599  *                                               <TT>num_elements_in_block</TT> returned from GetBlockInfo().
00600  * \param[out] element_ownership (int*)          The ownership array to store processor ID for all elements
00601  *                                               (array allocated by user).
00602  * \return ErrCode                               The error code indicating success or failure.
00603  */
00604 ErrCode iMOAB_GetElementOwnership( iMOAB_AppID pid,
00605                                    iMOAB_GlobalID* global_block_ID,
00606                                    int* num_elements_in_block,
00607                                    int* element_ownership );
00608 
00609 /**
00610  * \brief Get the global IDs for all locally visible elements belonging to a particular block.
00611  *
00612  * \note The method will return also the local index of each element, in the local range that contains
00613  * all visible elements.
00614  *
00615  * <B>Operations:</B> Not Collective
00616  *
00617  * \param[in]  pid (iMOAB_AppID)                   The unique pointer to the application ID.
00618  * \param[in]  global_block_ID (iMOAB_GlobalID*)   The global block ID of the set being queried.
00619  * \param[in]  num_elements_in_block (int*)        The allocated size of global element ID array, same as
00620  *                                                 <TT>num_elements_in_block</TT> returned from GetBlockInfo().
00621  * \param[out] global_element_ID (iMOAB_GlobalID*) The global IDs for all locally visible elements
00622  *                                                 (array allocated by user).
00623  * \param[out] local_element_ID (iMOAB_LocalID*)   (<I><TT>Optional</TT></I>) The local IDs for all locally visible
00624  *                                                 elements (index in the range of all primary elements in the rank)
00625  * \return ErrCode                                 The error code indicating success or failure.
00626  */
00627 ErrCode iMOAB_GetElementID( iMOAB_AppID pid,
00628                             iMOAB_GlobalID* global_block_ID,
00629                             int* num_elements_in_block,
00630                             iMOAB_GlobalID* global_element_ID,
00631                             iMOAB_LocalID* local_element_ID );
00632 
00633 /**
00634  * \brief Get the surface boundary condition information.
00635  *
00636  * \note <B>Operations:</B> Not Collective
00637  *
00638  * \param[in]  pid (iMOAB_AppID)                  The unique pointer to the application ID.
00639  * \param[in]  surface_BC_length (int*)           The allocated size of surface boundary condition array, same
00640  *                                                as <TT>num_visible_surfaceBC</TT> returned by GetMeshInfo().
00641  * \param[out] local_element_ID (iMOAB_LocalID*)  The local element IDs that contains the side with the surface BC.
00642  * \param[out] reference_surface_ID (int*)        The surface number with the BC in the canonical reference
00643  *                                                element (e.g., 1 to 6 for HEX, 1-4 for TET).
00644  * \param[out] boundary_condition_value (int*)    The boundary condition type as obtained from the mesh description
00645  *                                                (value of the NeumannSet defined on the element).
00646  * \return ErrCode                                The error code indicating success or failure.
00647  */
00648 ErrCode iMOAB_GetPointerToSurfaceBC( iMOAB_AppID pid,
00649                                      int* surface_BC_length,
00650                                      iMOAB_LocalID* local_element_ID,
00651                                      int* reference_surface_ID,
00652                                      int* boundary_condition_value );
00653 
00654 /**
00655  * \brief Get the vertex boundary condition information.
00656  *
00657  * \note <B>Operations:</B> Not Collective
00658  *
00659  * \param[in]  pid (iMOAB_AppID)                   The unique pointer to the application ID.
00660  * \param[in]  vertex_BC_length (int)              The allocated size of vertex boundary condition array, same as
00661  *                                                 <TT>num_visible_vertexBC</TT> returned by GetMeshInfo().
00662  * \param[out] local_vertex_ID (iMOAB_LocalID*)    The local vertex ID that has Dirichlet BC defined.
00663  * \param[out] boundary_condition_value (int*)     The boundary condition type as obtained from the mesh description
00664  *                                                 (value of the Dirichlet_Set tag defined on the vertex).
00665  * \return ErrCode                                 The error code indicating success or failure.
00666  */
00667 ErrCode iMOAB_GetPointerToVertexBC( iMOAB_AppID pid,
00668                                     int* vertex_BC_length,
00669                                     iMOAB_LocalID* local_vertex_ID,
00670                                     int* boundary_condition_value );
00671 
00672 /**
00673  * \brief Define a MOAB Tag corresponding to the application depending on requested types.
00674  *
00675  * \note In MOAB, for most solution vectors, we only need to create a "Dense", "Double" Tag. A sparse tag can
00676  * be created too. If the tag is already existing in the file, it will not be created. If it is a new tag,
00677  * memory will be allocated when setting the values. Default values are 0 for for integer tags, 0.0 for double tags,
00678  * 0 for entity handle tags.
00679  *
00680  * <B>Operations:</B> Collective
00681  *
00682  * \param[in] pid (iMOAB_AppID)               The unique pointer to the application ID.
00683  * \param[in] tag_storage_name (iMOAB_String) The tag name to store/retrieve the data in MOAB.
00684  * \param[in] tag_type (int*)                 The type of MOAB tag (Dense/Sparse, Double/Int/EntityHandle), enum MOAB_TAG_TYPE.
00685  * \param[in] components_per_entity (int*)    The total size of vector dimension per entity for the tag (e.g., number of doubles per entity).
00686  * \param[out] tag_index (int*)               The tag index which can be used as identifier in synchronize methods.
00687  * \return ErrCode                            The error code indicating success or failure.
00688  */
00689 ErrCode iMOAB_DefineTagStorage( iMOAB_AppID pid,
00690                                 const iMOAB_String tag_storage_name,
00691                                 int* tag_type,
00692                                 int* components_per_entity,
00693                                 int* tag_index );
00694 
00695 /**
00696  * \brief Store the specified values in a MOAB integer Tag.
00697  *
00698  * Values are set on vertices or elements, depending on entity_type
00699  *
00700  * \note we could change the api to accept as input the tag index, as returned by iMOAB_DefineTagStorage.
00701  *
00702  * <B>Operations:</B> Collective
00703  *
00704  * \param[in]  pid (iMOAB_AppID)                       The unique pointer to the application ID.
00705  * \param[in]  tag_storage_name (iMOAB_String)         The tag name to store/retreive the data in MOAB.
00706  * \param[in]  num_tag_storage_length (int*)           The size of tag storage data (e.g., num_visible_vertices*components_per_entity or
00707  *                                                     num_visible_elements*components_per_entity).
00708  * \param[in]  entity_type (int*)                      Type=0 for vertices, and Type=1 for primary elements.
00709  * \param[out] tag_storage_data (int*)                 The array data of type <I>int</I> to replace the internal tag memory;
00710  *                                                     The data is assumed to be contiguous over the local set of visible entities
00711  *                                                     (either vertices or elements).
00712  * \return ErrCode                                     The error code indicating success or failure.
00713  */
00714 ErrCode iMOAB_SetIntTagStorage( iMOAB_AppID pid,
00715                                 const iMOAB_String tag_storage_name,
00716                                 int* num_tag_storage_length,
00717                                 int* entity_type,
00718                                 int* tag_storage_data );
00719 
00720 /**
00721  * \brief Get the specified values in a MOAB integer Tag.
00722  *
00723  * \note <B>Operations:</B> Collective
00724  *
00725  * \param[in]  pid (iMOAB_AppID)                       The unique pointer to the application ID.
00726  * \param[in]  tag_storage_name (iMOAB_String)         The tag name to store/retreive the data in MOAB.
00727  * \param[in]  num_tag_storage_length (int*)           The size of tag storage data (e.g., num_visible_vertices*components_per_entity or
00728  *                                                     num_visible_elements*components_per_entity).
00729  * \param[in]  entity_type (int*)                      Type=0 for vertices, and Type=1 for primary elements.
00730  * \param[out] tag_storage_data (int*)                 The array data of type <I>int</I> to be copied from the internal tag memory;
00731  *                                                     The data is assumed to be contiguous over the local set of visible
00732  *                                                     entities (either vertices or elements).
00733  * \return ErrCode                                     The error code indicating success or failure.
00734  */
00735 ErrCode iMOAB_GetIntTagStorage( iMOAB_AppID pid,
00736                                 const iMOAB_String tag_storage_name,
00737                                 int* num_tag_storage_length,
00738                                 int* entity_type,
00739                                 int* tag_storage_data );
00740 
00741 /**
00742  * \brief Store the specified values in a MOAB double Tag.
00743  *
00744  * \note <B>Operations:</B> Collective
00745  *
00746  * \param[in]  pid (iMOAB_AppID)                       The unique pointer to the application ID.
00747  * \param[in]  tag_storage_name (iMOAB_String)         The tag names, separated, to store the data.
00748  * \param[in]  num_tag_storage_length (int*)           The size of total tag storage data (e.g., num_visible_vertices*components_per_entity
00749  *                                                     or num_visible_elements*components_per_entity*num_tags).
00750  * \param[in]  entity_type (int*)                      Type=0 for vertices, and Type=1 for primary elements.
00751  * \param[out] tag_storage_data (double*)              The array data of type <I>double</I> to replace the internal tag memory;
00752  *                                                     The data is assumed to be contiguous over the local set of visible
00753  *                                                     entities (either vertices or elements). unrolled by tags
00754  * \return ErrCode                                     The error code indicating success or failure.
00755  */
00756 ErrCode iMOAB_SetDoubleTagStorage( iMOAB_AppID pid,
00757                                    const iMOAB_String tag_storage_name,
00758                                    int* num_tag_storage_length,
00759                                    int* entity_type,
00760                                    double* tag_storage_data );
00761 
00762 /**
00763  * \brief Retrieve the specified values in a MOAB double Tag.
00764  *
00765  * \note <B>Operations:</B> Collective
00766  *
00767  * \param[in]  pid (iMOAB_AppID)                       The unique pointer to the application ID.
00768  * \param[in]  tag_storage_name (iMOAB_String)         The tag names to retrieve the data in MOAB.
00769  * \param[in]  num_tag_storage_length (int)            The size of total tag storage data (e.g., num_visible_vertices*components_per_entity*num_tags
00770  *                                                     or num_visible_elements*components_per_entity*num_tags)
00771  * \param[in]  entity_type (int*)                      Type=0 for vertices, and Type=1 for primary elements.
00772  * \param[out] tag_storage_data (double*)              The array data of type <I>double</I> to replace the internal tag memory;
00773  *                                                     The data is assumed to be contiguous over the local set of visible
00774  *                                                     entities (either vertices or elements). unrolled by tags
00775  * \return ErrCode                                     The error code indicating success or failure.
00776  */
00777 ErrCode iMOAB_GetDoubleTagStorage( iMOAB_AppID pid,
00778                                    const iMOAB_String tag_storage_name,
00779                                    int* num_tag_storage_length,
00780                                    int* entity_type,
00781                                    double* tag_storage_data );
00782 
00783 /**
00784  * \brief Exchange tag values for the given tags across process boundaries.
00785  *
00786  * \note <B>Operations:</B> Collective
00787  *
00788  * \param[in]  pid (iMOAB_AppID)                The unique pointer to the application ID.
00789  * \param[in]  num_tags (int*)                  Number of tags to exchange.
00790  * \param[in]  tag_indices (int*)               Array with tag indices of interest (size  = *num_tags).
00791  * \param[in]  ent_type (int*)                  The type of entity for tag exchange.
00792  * \return ErrCode                              The error code indicating success or failure.
00793  */
00794 ErrCode iMOAB_SynchronizeTags( iMOAB_AppID pid, int* num_tag, int* tag_indices, int* ent_type );
00795 
00796 /**
00797  * \brief Perform global reductions with the processes in the current applications communicator.
00798  * Specifically this routine performs reductions on the maximum value of the tag indicated by \ref tag_index.
00799  *
00800  * \note <B>Operations:</B> Collective
00801  *
00802  * \param[in]  pid (iMOAB_AppID)                The unique pointer to the application ID.
00803  * \param[in]  tag_index   (int*)               The tag index of interest.
00804  * \param[in]  ent_type (int*)                  The type of entity for tag reduction operation
00805  *                                              (vertices = 0, elements = 1)
00806  * \return ErrCode                              The error code indicating success or failure.
00807  */
00808 ErrCode iMOAB_ReduceTagsMax( iMOAB_AppID pid, int* tag_index, int* ent_type );
00809 
00810 /**
00811  * \brief Retrieve the adjacencies for the element entities.
00812  *
00813  * \note <B>Operations:</B> Not Collective
00814  *
00815  * \param[in]  pid (iMOAB_AppID)                      The unique pointer to the application ID.
00816  * \param[in]  local_index (iMOAB_LocalID*)           The local element ID for which adjacency information is needed.
00817  * \param[out] num_adjacent_elements (int*)           The total number of adjacent elements.
00818  * \param[out] adjacent_element_IDs (iMOAB_LocalID*)  The local element IDs of all adjacent elements to the current one
00819  *                                                    (typically, num_total_sides for internal elements or
00820  *                                                    num_total_sides-num_sides_on_boundary for boundary elements).
00821  * \return ErrCode                              The error code indicating success or failure.
00822  */
00823 ErrCode iMOAB_GetNeighborElements( iMOAB_AppID pid,
00824                                    iMOAB_LocalID* local_index,
00825                                    int* num_adjacent_elements,
00826                                    iMOAB_LocalID* adjacent_element_IDs );
00827 
00828 /**
00829  * \brief Get the adjacencies for the vertex entities.
00830  *
00831  * \todo The implementation may not be fully complete
00832  *
00833  * \note <B>Operations:</B> Not Collective
00834  *
00835  * \param[in]  pid (iMOAB_AppID)                      The unique pointer to the application ID.
00836  * \param[in]  local_vertex_ID (iMOAB_LocalID*)       The local vertex ID for which adjacency information is needed.
00837  * \param[out] num_adjacent_vertices (int*)           The total number of adjacent vertices.
00838  * \param[out] adjacent_vertex_IDs (iMOAB_LocalID*)   The local element IDs of all adjacent vertices to the current one
00839  *                                                    (typically, num_total_sides for internal elements or
00840  *                                                    num_total_sides-num_sides_on_boundary for boundary elements).
00841  * \return ErrCode                                    The error code indicating success or failure.
00842  */
00843 ErrCode iMOAB_GetNeighborVertices( iMOAB_AppID pid,
00844                                    iMOAB_LocalID* local_vertex_ID,
00845                                    int* num_adjacent_vertices,
00846                                    iMOAB_LocalID* adjacent_vertex_IDs );
00847 
00848 /**
00849  * \brief Set global information for number of vertices and number of elements;
00850  * It is usually available from the h5m file, or it can be computed with a MPI_Reduce.
00851  *
00852  * \param[in]  pid (iMOAB_AppID)               The unique pointer to the application ID.
00853  * \param[in]  num_global_verts (int*)         The number of total vertices in the mesh.
00854  * \param[in]  num_global_elems (MPI_Comm)     The number of total elements in the mesh.
00855  * \return ErrCode                             The error code indicating success or failure.
00856  */
00857 ErrCode iMOAB_SetGlobalInfo( iMOAB_AppID pid, int* num_global_verts, int* num_global_elems );
00858 
00859 /**
00860  * \brief Get global information about number of vertices and number of elements.
00861  *
00862  * \param[in]  pid (iMOAB_AppID)             The unique pointer to the application ID.
00863  * \param[in]  num_global_verts (int*)       The number of total vertices in the mesh.
00864  * \param[in]  num_global_elems (MPI_Comm)   The number of total elements in the mesh.
00865  * \return ErrCode                           The error code indicating success or failure.
00866  */
00867 ErrCode iMOAB_GetGlobalInfo( iMOAB_AppID pid, int* num_global_verts, int* num_global_elems );
00868 
00869 #ifdef MOAB_HAVE_MPI
00870 
00871 /**
00872  * \brief migrate (send) a set of elements from a group of tasks (senders) to another group of tasks (receivers)
00873  *
00874  * \note <B>Operations:</B>  Collective on sender group
00875  *
00876  * \param[in]  pid (iMOAB_AppID)                  The unique pointer to the application ID of the sender mesh.
00877  * \param[in]  joint_communicator (MPI_Comm)      The joint communicator that overlaps both the sender and receiver groups.
00878  * \param[in]  receivingGroup (MPI_Group *)       Receiving group information.
00879  * \param[in]  rcompid  (int*)                    External id of application that receives the mesh
00880  * \param[in]  method (int*)                      Partitioning ethod to use when sending the mesh;
00881  *                                                0=trivial, 1=Zoltan Graph (PHG), 2=Zoltan Geometric (RCB).
00882  * \return ErrCode                                The error code indicating success or failure.
00883  */
00884 ErrCode iMOAB_SendMesh( iMOAB_AppID pid,
00885                         MPI_Comm* joint_communicator,
00886                         MPI_Group* receivingGroup,
00887                         int* rcompid,
00888                         int* method );
00889 
00890 /**
00891  * \brief Free up all of the buffers that were allocated when data transfer between
00892  * components are performed. The nonblocking send and receive call buffers will be de-allocated
00893  * once all the data is received by all involved tasks.
00894  *
00895  * \param[in]  pid (iMOAB_AppID)                      The unique pointer to the application ID sender mesh.
00896  * \param[in]  context_id  (int*)                     The context used for sending, to identify the communication graph.
00897  * \return ErrCode                                    The error code indicating success of failure.
00898  */
00899 ErrCode iMOAB_FreeSenderBuffers( iMOAB_AppID pid, int* context_d );
00900 
00901 /**
00902  * \brief Migrate (receive) a set of elements from a sender group of tasks
00903  *
00904  * \note <B>Operations:</B>  Collective on receiver group
00905  *
00906  * \param[in]  pid (iMOAB_AppID)                      The unique pointer to the application ID  mesh (receiver).
00907  * \param[in]  joint_communicator (MPI_Comm*)         The joint communicator that overlaps both groups.
00908  * \param[in]  sending_group (MPI_Group *)            The group of processes that are sending the mesh.
00909  * \param[in]  sender_comp_id ( int *)                The unique application identifier that is sending the mesh
00910  * \return ErrCode                                    The error code indicating success or failure.
00911  */
00912 ErrCode iMOAB_ReceiveMesh( iMOAB_AppID pid,
00913                            MPI_Comm* joint_communicator,
00914                            MPI_Group* sending_group,
00915                            int* sender_comp_id );
00916 
00917 /**
00918  * \brief migrate (send) a list of tags, from a sender group of tasks to a receiver group of tasks
00919  *
00920  * \note <B>Operations:</B> Collective over the sender group, nonblocking sends
00921  *
00922  * \param[in]  pid (iMOAB_AppID)                      The unique pointer to the application ID of sender mesh.
00923  * \param[in]  tag_storage_name (const iMOAB_String)  The name of the tags to be sent between the processes.
00924  *                                                    Generally multiple tag names are concatenated, separated by ";".
00925  * \param[in]  joint_communicator (MPI_Comm)          The joint communicator that overlaps both groups.
00926  * \param[in]  context_id (int*)                      The identifier for the other participating component in the
00927  *                                                    intersection context (typically target); -1 if this refers to
00928  *                                                    the original migration of meshes (internal detail).
00929  * \return ErrCode                                    The error code indicating success or failure.
00930  */
00931 ErrCode iMOAB_SendElementTag( iMOAB_AppID pid,
00932                               const iMOAB_String tag_storage_name,
00933                               MPI_Comm* joint_communicator,
00934                               int* context_id );
00935 
00936 /**
00937  * \brief migrate (receive) a list of tags, from a sender group of tasks to a receiver group of tasks
00938  *
00939  * \note <B>Operations:</B> Collective over the receiver group, blocking receives
00940  *
00941  * \param[in]  pid (iMOAB_AppID)                      The unique pointer to the application ID of receiver mesh.
00942  * \param[in]  tag_storage_name (const iMOAB_String)  The name of the tags to be sent between the processes.
00943  *                                                    Generally multiple tag names are concatenated, separated by ";".
00944  * \param[in]  joint_communicator (MPI_Comm)          The joint communicator that overlaps both groups.
00945  * \param[in]  context_id (int*)                      The identifier for the other participating component in the
00946  *                                                    intersection context (typically target); -1 if this refers to
00947  *                                                    the original migration of meshes (internal detail).
00948  * \return ErrCode                                    The error code indicating success or failure.
00949  */
00950 ErrCode iMOAB_ReceiveElementTag( iMOAB_AppID pid,
00951                                  const iMOAB_String tag_storage_name,
00952                                  MPI_Comm* joint_communicator,
00953                                  int* context_id );
00954 
00955 /**
00956  * \brief Compute a communication graph between 2 iMOAB applications, based on ID matching of key data.
00957  *
00958  * \note <B>Operations:</B> Collective
00959  *
00960  * \param[in]  pid1 (iMOAB_AppID)                     The unique pointer to the first application ID.
00961  * \param[in]  pid2 (iMOAB_AppID)                     The unique pointer to the second application ID.
00962  * \param[in]  joint_communicator (MPI_Comm*)         The MPI communicator that overlaps both groups.
00963  * \param[in]  group1 (MPI_Group *)                   MPI group for first component.
00964  * \param[in]  group2 (MPI_Group *)                   MPI group for second component.
00965  * \param[in]  type1 (int *)                          The type of mesh used by pid1 (spectral with GLOBAL_DOFS, etc).
00966  * \param[in]  type2 (int *)                          The type of mesh used by pid2 (point cloud with GLOBAL_ID, etc).
00967  * \param[in]  comp1 (int*)                           The unique identifier of the first component.
00968  * \param[in]  comp2 (int*)                           The unique identifier of the second component.
00969  * \return ErrCode                                    The error code indicating success or failure.
00970  */
00971 ErrCode iMOAB_ComputeCommGraph( iMOAB_AppID pid1,
00972                                 iMOAB_AppID pid2,
00973                                 MPI_Comm* joint_communicator,
00974                                 MPI_Group* group1,
00975                                 MPI_Group* group2,
00976                                 int* type1,
00977                                 int* type2,
00978                                 int* comp1,
00979                                 int* comp2 );
00980 
00981 /**
00982  * \brief Recompute the communication graph between component and coupler, considering intersection coverage.
00983  *
00984  * \note Original communication graph for source used an initial partition, while during intersection some of the source
00985  * elements were sent to multiple tasks; send back the intersection coverage information for a direct communication
00986  * between source cx mesh on coupler tasks and source cc mesh on interested tasks on the component.
00987  * The intersection tasks will send to the original source component tasks, in a nonblocking way, the ids of all the
00988  * cells involved in intersection with the target cells. The new ParCommGraph between cc source mesh and cx source mesh
00989  * will be used just for tag migration, later on; The original ParCommGraph will stay unchanged, because this source mesh
00990  * could be used for other intersection (atm with lnd) ? on component source tasks, we will wait for information; from each
00991  * intersection task, will receive cells ids involved in intersection.
00992  *
00993  * \param[in]  joint_communicator (MPI_Comm *)     The joint communicator that overlaps component PEs and coupler PEs.
00994  * \param[in]  pid_src (iMOAB_AppID)               The unique application identifier for the component mesh on component PEs.
00995  * \param[in]  pid_migr (iMOAB_AppID)              The unique application identifier for the coupler mesh on coupler PEs.
00996  * \param[in]  pid_intx (iMOAB_AppID)              The unique application identifier representing the intersection context on coupler PEs.
00997  * \param[in]  src_id (int*)                       The external id for the component mesh on component PE.
00998  * \param[in]  migr_id (int*)                      The external id for the migrated mesh on coupler PEs.
00999  * \param[in]  context_id (int*)                   The unique identifier of the other participating component in intersection (target).
01000  * \return ErrCode                                 The error code indicating success or failure.
01001  */
01002 ErrCode iMOAB_CoverageGraph( MPI_Comm* joint_communicator,
01003                              iMOAB_AppID pid_src,
01004                              iMOAB_AppID pid_migr,
01005                              iMOAB_AppID pid_intx,
01006                              int* src_id,
01007                              int* migr_id,
01008                              int* context_id );
01009 
01010 /**
01011  * \brief Dump info about communication graph.
01012  *
01013  * \note <B>Operations:</B> Collective per sender or receiver group
01014  *
01015  * \param[in] pid  (iMOAB_AppID)          The unique pointer to the application ID.
01016  * \param[in] context_id  (int*)          The context_id names are separated by a semi-colon (";");
01017  *                                        This is similar to the specifications in tag migration.
01018  * \param[in] is_sender (int*)            Specify whether it is called from sender or receiver side.
01019  * \param[in] prefix  (iMOAB_String)      The prefix for file names in order to differentiate different stages.
01020  * \return ErrCode                        The error code indicating success or failure.
01021  */
01022 ErrCode iMOAB_DumpCommGraph( iMOAB_AppID pid, int* context_id, int* is_sender, const iMOAB_String prefix );
01023 
01024 /**
01025  * \brief merge vertices in an explicit, parallel mesh; it will also reassign global IDs on vertices,
01026  * and resolve parallel sharing of vertices.
01027  *
01028  * \note <B>Operations:</B> Collective
01029  *
01030  * \param[in]  pid (iMOAB_AppID)    The unique pointer to the application ID.
01031  * \return ErrCode                        The error code indicating success or failure.
01032  */
01033 ErrCode iMOAB_MergeVertices( iMOAB_AppID pid );
01034 
01035 #endif /* #ifdef MOAB_HAVE_MPI */
01036 
01037 #ifdef MOAB_HAVE_TEMPESTREMAP
01038 
01039 /**
01040  * @brief Compute intersection of the surface meshes defined on a sphere. The resulting intersected mesh consists
01041  * of (convex) polygons with 1-1 associativity with both the source and destination meshes provided.
01042  *
01043  * \note  The mesh intersection between two heterogeneous resolutions will be computed and stored in the fileset
01044  * corresponding to the \p pid_intersection application. This intersection data can be used to compute solution
01045  * projection weights between these meshes.
01046  *
01047  * <B>Operations:</B> Collective on coupler tasks
01048  *
01049  * \param[in]  pid_source (iMOAB_AppID)            The unique pointer to the source application ID.
01050  * \param[in]  pid_target (iMOAB_AppID)            The unique pointer to the destination application ID.
01051  * \param[out] pid_intersection (iMOAB_AppID)      The unique pointer to the intersection application ID.
01052  * \return ErrCode                                    The error code indicating success or failure.
01053  */
01054 ErrCode iMOAB_ComputeMeshIntersectionOnSphere( iMOAB_AppID pid_source,
01055                                                iMOAB_AppID pid_target,
01056                                                iMOAB_AppID pid_intersection );
01057 
01058 /**
01059  * \brief Compute the intersection of DoFs corresponding to surface meshes defined on a sphere. The resulting intersected
01060  * mesh essentially contains a communication pattern or a permutation matrix that couples both the source and destination
01061  * DoFs.
01062  *
01063  * \note <B>Operations:</B> Collective on coupler tasks
01064  *
01065  * \param[in]  pid_source (iMOAB_AppID)            The unique pointer to the source application ID.
01066  * \param[in]  pid_target (iMOAB_AppID)            The unique pointer to the destination application ID.
01067  * \param[out] pid_intersection (iMOAB_AppID)      The unique pointer to the intersection application ID.
01068  * \return ErrCode                                 The error code indicating success or failure.
01069  */
01070 ErrCode iMOAB_ComputePointDoFIntersection( iMOAB_AppID pid_source,
01071                                            iMOAB_AppID pid_target,
01072                                            iMOAB_AppID pid_intersection );
01073 
01074 #ifdef MOAB_HAVE_NETCDF
01075 
01076 #ifdef MOAB_HAVE_MPI
01077 
01078 /**
01079  * \brief Compute a communication graph between 2 moab apps, based on ID matching, between a component and map that
01080  * was read on coupler.
01081  *
01082  * \note Component can be target or source; also migrate meshes to coupler, from the components;
01083  * the mesh on coupler will be either source-like == coverage mesh or target-like the map is usually read
01084  * with rows fully distributed on tasks, so the target mesh will be a proper partition, while source mesh
01085  * coverage is dictated by the active columns on respective tasks.
01086  *
01087  * <B>Operations:</B> Collective
01088  *
01089  * \param[in]  pid1 (iMOAB_AppID)         The unique pointer to the first component.
01090  * \param[in]  pid2 (iMOAB_AppID)         The unique pointer to the second component.
01091  * \param[in]  pid3 (iMOAB_AppID)         The unique pointer to the coupler instance of the mesh (component 2).
01092  * \param[in]  join (MPI_Comm)            The joint communicator that overlaps both groups.
01093  * \param[in]  group1 (MPI_Group *)       The MPI group for the first component.
01094  * \param[in]  group2 (MPI_Group *)       The MPI group for the second component.
01095  * \param[in]  type1 (int *)              The type of mesh being migrated;
01096  *                                        (1) spectral with GLOBAL_DOFS, (2) Point Cloud (3) FV cell.
01097  * \param[in]  comp1 (int*)               The universally unique identifier of first component.
01098  * \param[in]  comp2 (int*)               The universally unique identifier of second component.
01099  * \param[in]  direction (int*)           A parameter indicating direction of the mesh migration.
01100  *                                        i.e., whether it is from source to coupler (1), or from coupler to target (2).
01101  * \return ErrCode                        The error code indicating success or failure.
01102 */
01103 ErrCode iMOAB_MigrateMapMesh( iMOAB_AppID pid1,
01104                               iMOAB_AppID pid2,
01105                               iMOAB_AppID pid3,
01106                               MPI_Comm* join,
01107                               MPI_Group* group1,
01108                               MPI_Group* group2,
01109                               int* type,
01110                               int* comp1,
01111                               int* comp2,
01112                               int* direction );
01113 
01114 #endif /* #ifdef MOAB_HAVE_MPI */
01115 
01116 /**
01117  * \brief Load the projection weights from disk to transfer a solution from a source surface mesh to a destination mesh defined on a sphere.
01118  * The intersection of the mesh should be computed a-priori.
01119  *
01120  * <B>Operations:</B> Collective
01121  *
01122  * \param[in] pid_intersection (iMOAB_AppID)               The unique pointer to the application ID to store the map
01123  * \param[in] pid_cpl (iMOAB_AppID)                        The unique pointer to coupler instance of component; (-1) for old load
01124  * \param[in] col_or_row (int *)                           The flag to indicate whether distribution is according to source (0) or target grid (1)
01125  * \param[in] type (int *)                                 type of mesh (1) spectral with GLOBAL_DOFS, (2) Point Cloud (3) FV cell
01126  * \param[in] solution_weights_identifier  (iMOAB_String)  The unique identifier used to store the computed projection weights locally. Typically,
01127  *                                                         values could be identifiers such as "scalar", "flux" or "custom".
01128  * \param[in] remap_weights_filename  (iMOAB_String)       The filename path to the mapping file to load in memory.
01129 */
01130 ErrCode iMOAB_LoadMappingWeightsFromFile(
01131     iMOAB_AppID pid_intersection,
01132     iMOAB_AppID pid_cpl,
01133     int* col_or_row,
01134     int* type,
01135     const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
01136     const iMOAB_String remap_weights_filename );
01137 
01138 /**
01139  * \brief Write the projection weights to disk in order to transfer a solution from a source surface mesh to a destination
01140  * mesh defined on a sphere.
01141  *
01142  * \note  <B>Operations:</B> Collective
01143  *
01144  * \param[in/out] pid_intersection (iMOAB_AppID)           The unique pointer to the application ID to store the map.
01145  * \param[in] solution_weights_identifier  (iMOAB_String)  The unique identifier used to store the computed projection weights locally. Typically,
01146  *                                                         values could be identifiers such as "scalar", "flux" or "custom".
01147  * \param[in] remap_weights_filename  (iMOAB_String)       The filename path to the mapping file to load in memory.
01148  * \return ErrCode                                         The error code indicating success or failure.
01149 */
01150 ErrCode iMOAB_WriteMappingWeightsToFile(
01151     iMOAB_AppID pid_intersection,
01152     const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
01153     const iMOAB_String remap_weights_filename );
01154 
01155 #endif /* #ifdef MOAB_HAVE_NETCDF */
01156 
01157 /**
01158  * \brief Compute the projection weights to transfer a solution from a source surface mesh to a destination mesh defined
01159  * on a sphere. The intersection of the mesh should be computed a-priori.
01160  *
01161  * \note
01162  * The mesh intersection data-structure is used along with conservative remapping techniques in TempestRemap to compute
01163  * the projection weights for transferring the tag (\p soln_tag_name) from \p pid_src to \p pid_target applications.
01164  *
01165  * <B>Operations:</B> Collective
01166  *
01167  * \param[in] pid_intersection (iMOAB_AppID)                The unique pointer to the intersection application ID.
01168  * \param[in] solution_weights_identifier  (iMOAB_String)   The unique identifier used to store the computed projection weights locally. Typically,
01169  *                                                          values could be identifiers such as "scalar", "flux" or "custom".
01170  * \param[in] disc_method_source  (iMOAB_String)            The discretization type ("fv", "cgll", "dgll") for the solution field on the source grid.
01171  * \param[in] disc_order_source   (int *)                   The discretization order for the solution field on the source grid.
01172  * \param[in] disc_method_target  (iMOAB_String)            The discretization type ("fv", "cgll", "dgll") for the solution field on the source grid.
01173  * \param[in] disc_order_target   (int *)                   The discretization order for the solution field on the source grid.
01174  * \param[in] fNoBubble           (int *)                   The flag to indicate whether to use bubbles in the interior of SE nodes.
01175  *                                                          Default: true i.e., no bubbles used.
01176  * \param[in] fMonotoneTypeID     (int *)                   The flag to indicate whether solution monotonicity is to be preserved. 0: none, 1: mono.
01177  * \param[in] fVolumetric         (int *)                   The flag to indicate whether we need to compute volumetric projection weights.
01178  * \param[in] fNoConservation     (int *)                   The flag to indicate whether to ignore conservation of solution field during projection.
01179  * \param[in] fValidate           (int *)                   The flag to indicate whether to validate the consistency and conservation of solution field during projection;
01180  *                                                          Production runs should not have this flag enabled to minimize collective operations.
01181  * \param[in] source_solution_tag_dof_name   (iMOAB_String) The global DoF IDs corresponding to participating degrees-of-freedom for the source discretization.
01182  * \param[in] target_solution_tag_dof_name   (iMOAB_String) The global DoF IDs corresponding to participating degrees-of-freedom for the target discretization.
01183  * \return ErrCode                                          The error code indicating success or failure.
01184 */
01185 ErrCode iMOAB_ComputeScalarProjectionWeights(
01186     iMOAB_AppID pid_intersection,
01187     const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
01188     const iMOAB_String disc_method_source,
01189     int* disc_order_source,
01190     const iMOAB_String disc_method_target,
01191     int* disc_order_target,
01192     int* fNoBubble,
01193     int* fMonotoneTypeID,
01194     int* fVolumetric,
01195     int* fInverseDistanceMap,
01196     int* fNoConservation,
01197     int* fValidate,
01198     const iMOAB_String source_solution_tag_dof_name,
01199     const iMOAB_String target_solution_tag_dof_name );
01200 
01201 /**
01202  * \brief Apply the projection weights matrix operator onto the source tag in order to compute the solution (tag)
01203  * represented on the target grid. This operation can be understood as the application of a matrix vector product
01204  * (Y=P*X).
01205  *
01206  * \note <B>Operations:</B> Collective
01207  *
01208  * \param[in] pid_intersection (iMOAB_AppID)                The unique pointer to the intersection application ID.
01209  * \param[in] solution_weights_identifier  (iMOAB_String)   The unique identifier used to store the computed projection weights locally. Typically,
01210  *                                                          values could be identifiers such as "scalar", "flux" or "custom".
01211  * \param[in] source_solution_tag_name   (iMOAB_String)     list of tag names corresponding to participating degrees-of-freedom for the source discretization;
01212  *                                                          names are separated by ";", the same way as for tag migration.
01213  * \param[in] target_solution_tag_name   (iMOAB_String)     list of tag names corresponding to participating degrees-of-freedom for the target discretization;
01214  *                                                          names are separated by ";", the same way as for tag migration.
01215  * \return ErrCode                                          The error code indicating success or failure.
01216 */
01217 ErrCode iMOAB_ApplyScalarProjectionWeights(
01218     iMOAB_AppID pid_intersection,
01219     const iMOAB_String solution_weights_identifier, /* "scalar", "flux", "custom" */
01220     const iMOAB_String source_solution_tag_name,
01221     const iMOAB_String target_solution_tag_name );
01222 
01223 #endif /* #ifdef MOAB_HAVE_TEMPESTREMAP */
01224 
01225 #ifdef MOAB_HAVE_MPI
01226 
01227 /**
01228  * Helper functions for MPI type conversions between Fortran and C++
01229  */
01230 
01231 /**
01232  * \brief MOAB MPI helper function to convert from a C-based MPI_Comm object
01233  * to a Fortran compatible MPI_Fint (integer) value.
01234  *
01235  * \param comm       Input MPI_Comm C-object pointer.
01236  * \return MPI_Fint  Output Fortran integer representing the comm object.
01237  */
01238 inline MPI_Fint MOAB_MPI_Comm_c2f( MPI_Comm* comm )
01239 {
01240     return MPI_Comm_c2f( *comm );
01241 }
01242 
01243 /**
01244  * \brief MOAB MPI helper function to convert from a Fortran-based MPI_Fint (integer)
01245  * value to a C/C++ compatible MPI_Comm object.
01246  *
01247  * \param fgroup (MPI_Fint)  Input Fortran integer representing the MPI_Comm object.
01248  * \return MPI_Comm*         Output C/C++-compatible MPI_Comm object pointer.
01249  */
01250 inline MPI_Comm* MOAB_MPI_Comm_f2c( MPI_Fint fcomm )
01251 {
01252     MPI_Comm* ccomm;
01253     ccomm  = (MPI_Comm*)( malloc( sizeof( MPI_Comm ) ) );  // memory leak ?!
01254     *ccomm = MPI_Comm_f2c( fcomm );
01255     if( *ccomm == MPI_COMM_NULL )
01256     {
01257         free( ccomm );
01258         IMOAB_THROW_ERROR( "The MPI_Comm conversion from Fortran to C failed.", NULL );
01259     }
01260     else
01261         return ccomm;
01262 }
01263 
01264 /**
01265  * \brief MOAB MPI helper functions to convert from a C-based MPI_Group object
01266  * to a Fortran compatible MPI_Fint (integer) value.
01267  *
01268  * \param group      Input MPI_Comm C-object pointer.
01269  * \return MPI_Fint  Output Fortran integer representing the comm object.
01270  */
01271 inline MPI_Fint MOAB_MPI_Group_c2f( MPI_Group* group )
01272 {
01273     return MPI_Group_c2f( *group );
01274 }
01275 
01276 /**
01277  * \brief MOAB MPI helper function to convert from a Fortran-based MPI_Fint (integer)
01278  * value to a C/C++ compatible MPI_Group object.
01279  *
01280  * \param fgroup (MPI_Fint)   Input Fortran integer representing the MPIGroup object.
01281  * \return MPI_Group*         Output C/C++-compatible MPI_Group object pointer.
01282  */
01283 inline MPI_Group* MOAB_MPI_Group_f2c( MPI_Fint fgroup )
01284 {
01285     MPI_Group* cgroup;
01286     cgroup  = (MPI_Group*)( malloc( sizeof( MPI_Group ) ) );  // memory leak ?!
01287     *cgroup = MPI_Group_f2c( fgroup );
01288     if( *cgroup == MPI_GROUP_NULL )
01289     {
01290         free( cgroup );
01291         IMOAB_THROW_ERROR( "The MPI_Group conversion from Fortran to C failed.", NULL );
01292     }
01293     else
01294         return cgroup;
01295 }
01296 
01297 #endif /* #ifdef MOAB_HAVE_MPI */
01298 
01299 #ifdef __cplusplus
01300 }
01301 #endif /* #ifdef __cplusplus */
01302 
01303 #endif /* #ifndef IMOAB_H */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines