MOAB: Mesh Oriented datABase  (version 5.4.1)
iMeshP.h
Go to the documentation of this file.
00001 #ifndef _ITAPS_iMeshP
00002 #define _ITAPS_iMeshP
00003 
00004 #include "iMesh.h"
00005 #include "iMeshP_protos.h"
00006 #include "moab_mpi.h"
00007 
00008 #ifdef __cplusplus
00009 extern "C" {
00010 #endif
00011 
00012 /** Handles needed in iMeshP */
00013 typedef struct iMeshP_PartitionHandle_Private* iMeshP_PartitionHandle;
00014 typedef struct iMeshP_RequestHandle_Private* iMeshP_RequestHandle;
00015 
00016 /* Since we allow overloading of iMesh functions' entity set handles with
00017  * part handles, iMeshP_PartHandle must be defined the same as
00018  * iBase_EntitySetHandle. */
00019 typedef iBase_EntitySetHandle iMeshP_PartHandle;
00020 
00021 typedef unsigned iMeshP_Part;
00022 
00023 /** Types for classifying entities within a part. */
00024 enum iMeshP_EntStatus
00025 {
00026     iMeshP_INTERNAL, /**< An owned entity that is not on a part boundary. */
00027     iMeshP_BOUNDARY, /**< A shared entity on a part boundary. */
00028     iMeshP_GHOST     /**< An entity copy that is not a shared boundary entity. */
00029 };
00030 
00031 /** Part ID number indicating information should be returned about all parts. */
00032 #define iMeshP_ALL_PARTS ( -1 )
00033 
00034 /** \page imeshp  iMeshP: ITAPS Parallel Mesh Interface
00035 iMeshP.h -- ITAPS Parallel Mesh Interface
00036 
00037 Release 0.1; October 2008
00038 
00039 \section ADM Abstract Data Model
00040 -  The term "mesh" refers to an abstraction in the data model;
00041    it does not imply a serial or parallel distribution.
00042 -  The term "partition" refers to an assignment of a set of entities to
00043    subsets; like a "mesh," it does not imply a serial or parallel
00044    implementation.
00045 -  An application may use one or more meshes.
00046 -  Partitions can create subsets of entities from one or more meshes.
00047 -  Meshes can be subdivided by one or more partitions.
00048 -  Partitions contain parts.  Parts contain the subsets of entities in the
00049    partition.
00050 
00051 \section PAR Parallelism
00052 -  A "process" can be thought of as an MPI process. The
00053    number of processes can be considered to be the result of MPI_Comm_size.
00054    The rank of a process can be thought of as the result of MPI_Comm_rank.
00055    We will think in terms of processes rather than processors.  Initial
00056    implementations of the parallel interface will likely use MPI terminology
00057    directly; future implementations may accommodate other communication
00058    paradigms and libraries.
00059 -  Partitions have communicators associated with them.  These communicators
00060    can be thought of as MPI communicators.
00061 -  "Global" operations are operations performed with respect to a
00062    partition's communicator.
00063 -  "Local" operations are operations performed with respect to a part or
00064    a mesh instance within a process.
00065 -  Part A "neighbors" Part B if Part A has copies of entities owned by Part B
00066    and/or if Part B has copies of entities owned by Part A.
00067 
00068 \section INT Interfaces
00069 -  Each process has one or more "mesh instances."  A mesh instance can be
00070    thought of as a mesh database.  An implementation should support the
00071    existence of more than one mesh instance per process (e.g., it should
00072    always associate mesh data with a mesh instance).  However, we expect
00073    applications would most often use only one mesh instance per process.
00074 -  There is one root set per mesh instance.
00075 -  Each process may have one or more partition handles.
00076 -  A partition assigns entities from one mesh instance to parts.
00077 -  Entities in a mesh instance can be partitioned by one or more partitions.
00078    Mesh instances know which partitions they contain.
00079 -  Parts are uniquely identified globally by part IDs of type iMeshP_Part.
00080    Local parts can also be accessed by part handles that provide more
00081    direct access to a part.
00082    Functions accepting part handles operate correctly on only local
00083    parts (parts on the calling process); they will return an error
00084    for remote (off-process) parts.
00085 -  Generation and management of global IDs for entities
00086    is not included in the iMeshP interface.  It can
00087    be provided as a service above the iMeshP interface.
00088    Uniqueness of global IDs is managed at the partition level.
00089 
00090 \section PRT Using Parts
00091 -  Each part is wholly contained within a process.
00092 -  A process may have zero, one or multiple parts.
00093 -  For each entity that is copied onto remote parts, the owning part knows
00094    both the remote part ID and remote entity handle of all copies.
00095 -  All parts with copies of a boundary entity know the remote part ID
00096    and remote entity handle of all copies of the entity.
00097 -  All parts with copies of any entity know the part ID and
00098    entity handle corresponding to the owner of the entity.
00099 -  Functions that return entity information for a part, set or mesh
00100    instance return the information for all entities (including copies and
00101    ghosts) in that part, set or mesh instance.  Applications can check
00102    whether an entity is owned or a ghost using iMeshP_isEntOwner or
00103    iMeshP_getEntStatus.
00104 -  Many iMesh functions that accept an iBase_EntitySetHandle
00105    are also useful in the context of a iMeshP_PartHandle.
00106    These functions are reinterpreted so that they can accept either an
00107    iBase_EntitySetHandle or an iMeshP_PartHandle.
00108 -  In particular, entities are added to and removed from local parts via
00109    the same functions that are used to manipulate entity sets.
00110    That is, given a mesh instance, an entity handle, and a part handle,
00111    the entity is added to or removed from the part via calls to
00112    the following functions with the part handle passed as the entity set handle:
00113    - Add entity to part --> iMesh_addEntToSet
00114    - Remove entity from part --> iMesh_rmvEntFromSet
00115    - Add array of entities to part --> iMesh_addEntArrToSet
00116    - Remove array of entities from part --> iMesh_rmvEntArrFromSet
00117 
00118 \section CMM Communication
00119 -  Each function description includes its communication requirements.  The
00120    options are described here:
00121    -  COMMUNICATION:  Collective -- the function must be called by all
00122       processes in the partition's communicator.  (These functions have the
00123       suffix "All" to indicate collective communication is done.)
00124    -  COMMUNICATION:  Point-to-Point -- communication is used, but the
00125       communication is from one process to only one other process.  The
00126       receiving process must issue an appropriate receive call to receive
00127       the message.
00128    -  COMMUNICATION:  None -- the function does not use communication; only
00129       local operations are performed.
00130    -  COMMUNICATION:  None++ -- no communication is done; the values
00131       are precomputed by iMeshP_syncPartitionAll or iMeshP_syncMeshAll.
00132 -  Non-blocking calls for off-processor mesh-modification return a request
00133    that indicates whether or not the operation has completed.  The request
00134    is more than an MPI request; it encapsulates both the MPI information and
00135    the mesh operations that were requested.  If non-blocking calls are used,
00136    appropriate calls to iMeshP "wait" or "poll" functions must be used to
00137    handle and satisfy requests.
00138 */
00139 
00140 /*------------------------------------------------------------------------*/
00141 /*------------------------------------------------------------------------*/
00142 /*                          Partition Functionality                       */
00143 /*------------------------------------------------------------------------*/
00144 /*------------------------------------------------------------------------*/
00145 
00146 /** \brief Create a partition; return its handle.
00147  *
00148  *  Given a mesh instance and a communicator,
00149  *  return a partition handle for a new partition within the mesh instance
00150  *  that uses the communicator.
00151  *  In the future, we may have different creation routines for different
00152  *  communication systems; once the partition is created, the application
00153  *  would not have to worry about the communication system again.
00154  *  For now, implementations are MPI based, so MPI communicators are provided.
00155  *  For serial use, the communicator may be MPI_COMM_SELF or communicator may
00156  *  be NULL.
00157  *
00158  *  COMMUNICATION:  Collective.
00159  *
00160  *  \param  instance         (In)  Mesh instance to contain the partition.
00161  *  \param  communicator     (In)  Communicator to be used for parallel
00162  *                                 communication.
00163  *  \param  partition        (Out) The newly created partition.
00164  *  \param  err              (Out) Error code.
00165  */
00166 void iMeshP_createPartitionAll( iMesh_Instance instance,
00167                                 MPI_Comm communicator,
00168                                 iMeshP_PartitionHandle* partition,
00169                                 int* err );
00170 
00171 /**  \brief Destroy a partition.
00172  *
00173  *  Given a partition handle,
00174  *  destroy the partition associated with the handle.
00175  *  Note that the partition handle is not invalidated upon return.
00176  *
00177  *  COMMUNICATION:  Collective.
00178  *
00179  *  \param  instance         (In)  Mesh instance containing the partition.
00180  *  \param  partition        (In)  The partition to be destroyed.
00181  *  \param  err              (Out) Error code.
00182  */
00183 void iMeshP_destroyPartitionAll( iMesh_Instance instance, iMeshP_PartitionHandle partition, int* err );
00184 
00185 /**  \brief Return communicator associated with a partition.
00186  *
00187  *  Given a partition handle, return the communicator associated with
00188  *  it during its creation by iMeshP_createPartitionAll.
00189  *
00190  *  COMMUNICATION:  None
00191  *
00192  *  \param  instance         (In)  Mesh instance containing the partition.
00193  *  \param  partition        (In)  The partition being queried.
00194  *  \param  communicator     (Out) Communicator associated with the partition.
00195  *  \param  err              (Out) Error code.
00196  */
00197 void iMeshP_getPartitionComm( iMesh_Instance instance,
00198                               iMeshP_PartitionHandle partition,
00199                               MPI_Comm* communicator,
00200                               int* err );
00201 
00202 /**  \brief Update a partition after parts have been added.
00203  *
00204  *  This function gives the implementation an opportunity to locally store info
00205  *  about the partition so that queries on the partition can be
00206  *  performed without synchronous communication.
00207  *  This function must be called after all parts have been added to the
00208  *  partition and after changes to the partition (e.g., due to load balancing).
00209  *  Values that are precomputed by syncPartitionAll include:
00210  *  -  the total number of parts in a partition;
00211  *  -  the mapping between part IDs and processes; and
00212  *  -  updated remote entity handle information.
00213  *
00214  *  COMMUNICATION:  Collective.
00215  *
00216  *  \param  instance         (In)  Mesh instance containing the partition.
00217  *  \param  partition        (In)  The partition being updated.
00218  *  \param  err              (Out) Error code.
00219  */
00220 void iMeshP_syncPartitionAll( iMesh_Instance instance, iMeshP_PartitionHandle partition, int* err );
00221 
00222 /**  \brief Return the number of partitions associated with a mesh instance.
00223  *
00224  *  Given a mesh instance, return the number of partition handles
00225  *  associated with the mesh instance.
00226  *
00227  *  COMMUNICATION:  None.
00228  *
00229  *  \param  instance         (In)  Mesh instance containing the partitions.
00230  *  \param  num_partitions   (Out) Number of partitions associated with the
00231  *                                 mesh instance.
00232  *  \param  err              (Out) Error code.
00233  */
00234 void iMeshP_getNumPartitions( iMesh_Instance instance, int* num_partitions, int* err );
00235 
00236 /**  \brief Return the partition handles associated with a mesh instance.
00237  *
00238  *  Given a mesh instance, return all partition handles
00239  *  associated with the mesh instance.
00240  *
00241  *  COMMUNICATION:  None.
00242  *
00243  *  \param  instance                    (In)     Mesh instance containing the
00244  *                                               partitions.
00245  *  \param  partitions                  (In/Out) Array of partition handles
00246  *                                               associated with the mesh
00247  *                                               instance.
00248  *  \param  partitions_allocated        (In/Out) Allocated size of
00249  *                                               partitions array.
00250  *  \param  partitions_size             (Out)    Occupied size of
00251  *                                               partitions array.
00252  *  \param  err                         (Out)    Error code.
00253  */
00254 void iMeshP_getPartitions( iMesh_Instance instance,
00255                            iMeshP_PartitionHandle** partitions,
00256                            int* partitions_allocated,
00257                            int* partitions_size,
00258                            int* err );
00259 
00260 /** \brief Return the global number of parts in a partition.
00261  *
00262  *  Given a partition handle, return the total number of parts
00263  *  in the partition across all processes in the partition's communicator.
00264  *
00265  *  COMMUNICATION:  None++.
00266  *
00267  *  \param  instance         (In)  Mesh instance containing the partition.
00268  *  \param  partition        (In)  The partition being queried.
00269  *  \param  num_global_part  (Out) Global number of parts in the partition.
00270  *  \param  err              (Out) Error code.
00271  */
00272 void iMeshP_getNumGlobalParts( iMesh_Instance instance,
00273                                const iMeshP_PartitionHandle partition,
00274                                int* num_global_part,
00275                                int* err );
00276 
00277 /** \brief Return the local number of parts in a partition.
00278  *
00279  *  Given a partition handle, return the number of local (on-process) parts
00280  *  in the partition.
00281  *
00282  *  COMMUNICATION:  None.
00283  *
00284  *  \param  instance         (In)  Mesh instance containing the partition.
00285  *  \param  partition        (In)  The partition being queried.
00286  *  \param  num_local_part   (Out) Local (on-process) number of parts in
00287  *                                 the partition.
00288  *  \param  err              (Out) Error code.
00289  */
00290 void iMeshP_getNumLocalParts( iMesh_Instance instance,
00291                               const iMeshP_PartitionHandle partition,
00292                               int* num_local_part,
00293                               int* err );
00294 
00295 /** \brief Return the part handles of local parts in a partition.
00296  *
00297  *  Given a partition handle, return the
00298  *  part handles for the local (on-process) parts in the partition.
00299  *
00300  *  COMMUNICATION:  None.
00301  *
00302  *  \param  instance               (In)     Mesh instance containing the
00303  *                                          partition.
00304  *  \param  partition              (In)     The partition being queried.
00305  *  \param  parts                  (In/Out) Array of part handles
00306  *                                          for local parts in the partition.
00307  *  \param  parts_allocated        (In/Out) Allocated size of
00308  *                                          parts array.
00309  *  \param  parts_size             (Out)    Occupied size of
00310  *                                          parts array.
00311  *  \param  err                    (Out)    Error code.
00312  */
00313 void iMeshP_getLocalParts( iMesh_Instance instance,
00314                            const iMeshP_PartitionHandle partition,
00315                            iMeshP_PartHandle** parts,
00316                            int* parts_allocated,
00317                            int* parts_size,
00318                            int* err );
00319 
00320 /**  \brief Return the process rank of a given part.
00321  *
00322  *  Given a partition handle and a part ID, return the process rank
00323  *  (with respect to the partition's communicator) of the
00324  *  process that owns the part. The part may be local or remote.
00325  *
00326  *  COMMUNICATION:  None++.
00327  *
00328  *  \param  instance         (In)  Mesh instance containing the partition.
00329  *  \param  partition        (In)  The partition being queried.
00330  *  \param  part_id          (In)  Part ID for the part being queried.
00331  *  \param  rank             (Out) Process rank of part_id.
00332  *  \param  err              (Out) Error code.
00333  */
00334 void iMeshP_getRankOfPart( iMesh_Instance instance,
00335                            const iMeshP_PartitionHandle partition,
00336                            const iMeshP_Part part_id,
00337                            int* rank,
00338                            int* err );
00339 
00340 /**  \brief Return the process ranks of given parts.
00341  *
00342  *  Given a partition handle and an array of part IDs, return the process ranks
00343  *  (with respect to the partition's communicator) of the
00344  *  process that owns each part. The parts may be local or remote.
00345  *
00346  *  COMMUNICATION:  None++.
00347  *
00348  *  \param  instance         (In)     Mesh instance containing the partition.
00349  *  \param  partition        (In)     The partition being queried.
00350  *  \param  part_ids         (In)     Array of Part IDs for the parts being
00351  *                                    queried.
00352  *  \param  part_ids_size    (In)     The number of Part IDs in part_ids.
00353  *  \param  ranks            (In/Out) Array of ranks for the Part Ids in
00354  *                                    part_ids.
00355  *  \param  ranks_allocated  (In/Out) Allocated size of ranks array.
00356  *  \param  ranks_size       (Out)    Occupied size of ranks array.
00357  *  \param  err              (Out)    Error code.
00358  */
00359 void iMeshP_getRankOfPartArr( iMesh_Instance instance,
00360                               const iMeshP_PartitionHandle partition,
00361                               const iMeshP_Part* part_ids,
00362                               const int part_ids_size,
00363                               int** ranks,
00364                               int* ranks_allocated,
00365                               int* ranks_size,
00366                               int* err );
00367 
00368 /** \brief  Return the number of entities of a given type in a partition.
00369  *
00370  *  Given a partition handle and an entity set (possibly the root set),
00371  *  return the global number of  entities of a
00372  *  given entity type in the partition and set.  This function may require
00373  *  communication and, thus, must be called by all processes in the partition's
00374  *  communicator.
00375  *
00376  *  COMMUNICATION:  Collective.
00377  *
00378  *  \param  instance          (In)  Mesh instance containing the partition.
00379  *  \param  partition         (In)  The partition being queried.
00380  *  \param  entity_set        (In)  Entity set handle for the entity set
00381  *                                  being queried.
00382  *  \param  entity_type       (In)  Requested entity type;
00383  *                                  may be iBase_ALL_TYPES.
00384  *  \param  num_type          (Out) Number of entities of entity_type in
00385  *                                  the partition and entity set.
00386  *  \param  err               (Out) Error code.
00387  */
00388 void iMeshP_getNumOfTypeAll( iMesh_Instance instance,
00389                              const iMeshP_PartitionHandle partition,
00390                              const iBase_EntitySetHandle entity_set,
00391                              int entity_type,
00392                              int* num_type,
00393                              int* err );
00394 
00395 /** \brief  Return the number of entities of a given topology in a partition.
00396  *
00397  *  Given a partition handle and an entity set (possibly the root set),
00398  *  return the global number of  entities of a
00399  *  given entity topology in the partition and set.  This function may require
00400  *  communication and, thus, must be called by all processes in the partition's
00401  *  communicator.
00402  *
00403  *  COMMUNICATION:  Collective.
00404  *
00405  *  \param  instance          (In)  Mesh instance containing the partition.
00406  *  \param  partition         (In)  The partition being queried.
00407  *  \param  entity_set        (In)  Entity set handle for the entity set
00408  *                                  being queried; may be the root set.
00409  *  \param  entity_topology   (In)  Requested entity topology;
00410  *                                  may be iMesh_ALL_TOPOLOGIES.
00411  *  \param  num_topo          (Out) Number of entities with entity_topology in
00412  *                                  the partition and entity set.
00413  *  \param  err               (Out) Error code.
00414  */
00415 void iMeshP_getNumOfTopoAll( iMesh_Instance instance,
00416                              const iMeshP_PartitionHandle partition,
00417                              const iBase_EntitySetHandle entity_set,
00418                              int entity_topology,
00419                              int* num_topo,
00420                              int* err );
00421 
00422 /*------------------------------------------------------------------------*/
00423 /*------------------------------------------------------------------------*/
00424 /*                        Part Functionality                              */
00425 /*------------------------------------------------------------------------*/
00426 /*------------------------------------------------------------------------*/
00427 
00428 /** \brief Create a new part in a partition.
00429  *
00430  *  Given a partition handle, create a new part and add it to the
00431  *  partition on the process invoking the creation.  Return the part handle
00432  *  for the new part.
00433  *
00434  *  COMMUNICATION:  None.
00435  *
00436  *  \param  instance          (In)  Mesh instance containing the partition.
00437  *  \param  partition         (In)  The partition being updated.
00438  *  \param  part              (Out) The newly created part.
00439  *  \param  err               (Out) Error code.
00440  */
00441 void iMeshP_createPart( iMesh_Instance instance, iMeshP_PartitionHandle partition, iMeshP_PartHandle* part, int* err );
00442 
00443 /** \brief  Remove a part from a partition.
00444  *
00445  *  Given a partition handle and a part handle, remove the part
00446  *  from the partition and destroy the part.  Note that the part handle
00447  *  is not invalidated by this function.
00448  *
00449  *  COMMUNICATION:  None.
00450  *
00451  *  \param  instance          (In)  Mesh instance containing the partition.
00452  *  \param  partition         (In)  The partition being updated.
00453  *  \param  part              (In)  The part to be removed.
00454  *  \param  err               (Out) Error code.
00455  */
00456 void iMeshP_destroyPart( iMesh_Instance instance, iMeshP_PartitionHandle partition, iMeshP_PartHandle part, int* err );
00457 
00458 /** \brief Obtain a part ID from a part handle.
00459  *
00460  *  Given a partition handle and a local part handle, return the part ID.
00461  *  If the part handle is not a valid part handle for a local part,
00462  *  an error is returned.
00463  *
00464  *  COMMUNICATION:  None.
00465  *
00466  *  \param  instance          (In)  Mesh instance containing the partition.
00467  *  \param  partition         (In)  The partition being queried.
00468  *  \param  part              (In)  The part being queried.
00469  *  \param  part_id           (Out) Part ID for part.
00470  *  \param  err               (Out) Error code.
00471  */
00472 void iMeshP_getPartIdFromPartHandle( iMesh_Instance instance,
00473                                      const iMeshP_PartitionHandle partition,
00474                                      const iMeshP_PartHandle part,
00475                                      iMeshP_Part* part_id,
00476                                      int* err );
00477 
00478 /** \brief Obtain part IDs from part handles.
00479  *
00480  *  Given a partition handle and an array of local part handles,
00481  *  return the part ID for each part handle.
00482  *  If any part handle is not a valid part handle for a local part,
00483  *  an error is returned.
00484  *
00485  *  COMMUNICATION:  None.
00486  *
00487  *  \param  instance            (In)     Mesh instance containing the partition.
00488  *  \param  partition           (In)     The partition being queried.
00489  *  \param  parts               (In)     Array of part handles for the parts
00490  *                                       being queried.
00491  *  \param  parts_size          (In)     Number of part handles being queried.
00492  *  \param  part_ids            (In/Out) Array of part IDs associated with the
00493  *                                       parts.
00494  *  \param  part_ids_allocated  (In/Out) Allocated size of part_ids array.
00495  *  \param  part_ids_size       (Out)    Occupied size of part_ids array.
00496  *  \param  err                 (Out)    Error code.
00497  */
00498 void iMeshP_getPartIdsFromPartHandlesArr( iMesh_Instance instance,
00499                                           const iMeshP_PartitionHandle partition,
00500                                           const iMeshP_PartHandle* parts,
00501                                           const int parts_size,
00502                                           iMeshP_Part** part_ids,
00503                                           int* part_ids_allocated,
00504                                           int* part_ids_size,
00505                                           int* err );
00506 
00507 /** \brief Obtain a part handle from a part ID.
00508  *
00509  *  Given a partition handle and a part ID, return the part handle
00510  *  associated with the part
00511  *  if the part is local; otherwise, return an error code.
00512  *
00513  *  COMMUNICATION:  None.
00514  *
00515  *  \param  instance          (In)  Mesh instance containing the partition.
00516  *  \param  partition         (In)  The partition being queried.
00517  *  \param  part_id           (In)  Part ID for the part being queried.
00518  *  \param  part              (Out) Part handle associated with part_id.
00519  *  \param  err               (Out) Error code.
00520  */
00521 void iMeshP_getPartHandleFromPartId( iMesh_Instance instance,
00522                                      const iMeshP_PartitionHandle partition,
00523                                      iMeshP_Part part_id,
00524                                      iMeshP_PartHandle* part,
00525                                      int* err );
00526 
00527 /** \brief Obtain part handles from part IDs.
00528  *
00529  *  Given a partition handle and an array of local part IDs,
00530  *  return the part handle for each part ID.
00531  *  If any part ID is not a valid part ID for a local part,
00532  *  an error is returned.
00533  *
00534  *  COMMUNICATION:  None.
00535  *
00536  *  \param  instance                (In)     Mesh instance containing the
00537  *                                           partition.
00538  *  \param  partition               (In)     The partition being queried.
00539  *  \param  part_ids                (In)     Array of part IDs for the parts
00540  *                                           being queried.
00541  *  \param  part_ids_size           (In)     Number of part IDs being queried.
00542  *  \param  parts                   (In/Out) Array of part handles associated
00543  *                                           with the part_ids.
00544  *  \param  parts_allocated         (In/Out) Allocated size of parts
00545  *                                           array.
00546  *  \param  parts_size              (Out)    Occupied size of parts
00547  *                                           array.
00548  *  \param  err                     (Out)    Error code.
00549  */
00550 void iMeshP_getPartHandlesFromPartsIdsArr( iMesh_Instance instance,
00551                                            const iMeshP_PartitionHandle partition,
00552                                            const iMeshP_Part* part_ids,
00553                                            const int part_ids_size,
00554                                            iMeshP_PartHandle** parts,
00555                                            int* parts_allocated,
00556                                            int* parts_size,
00557                                            int* err );
00558 
00559 /*------------------------------------------------------------------------*/
00560 /*                        Part Boundaries                                 */
00561 /*------------------------------------------------------------------------*/
00562 
00563 /** \brief Return the number of parts that neighbor a given part.
00564  *
00565  *  Given a partition handle, a part handle, and an entity type,
00566  *  return the number of parts in the partition that neighbor the given part
00567  *  (i.e., that (1) have copies of entities of the given entity type owned by
00568  *  the given part or (2) own entities of the given entity type that are
00569  *  copied on the given part).
00570  *
00571  *  COMMUNICATION:  None++.
00572  *
00573  *  \param  instance          (In)  Mesh instance containing the partition.
00574  *  \param  partition         (In)  The partition being queried.
00575  *  \param  part              (In)  The part being queried.
00576  *  \param  entity_type       (In)  Entity type of the copied entities;
00577  *                                  may be iBase_ALL_TYPES.
00578  *  \param  num_part_nbors    (Out) Number of parts neighboring the given part.
00579  *  \param  err               (Out) Error code.
00580  */
00581 void iMeshP_getNumPartNbors( iMesh_Instance instance,
00582                              const iMeshP_PartitionHandle partition,
00583                              const iMeshP_PartHandle part,
00584                              int entity_type,
00585                              int* num_part_nbors,
00586                              int* err );
00587 
00588 /** \brief Return the number of parts that neighbor given parts.
00589  *
00590  *  Given a partition handle, an array of part handles, and an entity type,
00591  *  return the number of parts in the partition that neighbor each of the
00592  *  given parts
00593  *  (i.e., that (1) have copies of entities of the given entity type owned by
00594  *  the given part or (2) own entities of the given entity type that are
00595  *  copied on the given part).
00596  *
00597  *  COMMUNICATION:  None++.
00598  *
00599  *  \param  instance                  (In)     Mesh instance containing the
00600  *                                             partition.
00601  *  \param  partition                 (In)     The partition being queried.
00602  *  \param  parts                     (In)     Array of part handles for the
00603  *                                             parts being queried.
00604  *  \param  parts_size                (In)     Number of part handles in
00605  *                                             parts.
00606  *  \param  entity_type               (In)     Entity type of the copied
00607  *                                             entities;
00608  *                                             may be iBase_ALL_TYPES.
00609  *  \param  num_part_nbors            (In/Out) Array of values specifying the
00610  *                                             number of part neighbors for
00611  *                                             each part in parts.
00612  *  \param  num_part_nbors_allocated  (In/Out) Allocated size of num_part_nbors
00613  *                                             array.
00614  *  \param  num_part_nbors_size       (Out)    Occupied size of num_part_nbors
00615  *                                             array.
00616  *  \param  err                       (Out)    Error code.
00617  */
00618 void iMeshP_getNumPartNborsArr( iMesh_Instance instance,
00619                                 const iMeshP_PartitionHandle partition,
00620                                 const iMeshP_PartHandle* parts,
00621                                 int parts_size,
00622                                 int entity_type,
00623                                 int** num_part_nbors,
00624                                 int* num_part_nbors_allocated,
00625                                 int* num_part_nbors_size,
00626                                 int* err );
00627 
00628 /** \brief Return the parts that neighbor a given part.
00629  *
00630  *  Given a partition handle, a part handle, and an entity type,
00631  *  return the part IDs of parts that neighbor the given part
00632  *  (i.e., that (1) have copies of entities of the given entity type owned by
00633  *  the given part or (2) own entities of the given entity type that are
00634  *  copied on the given part).
00635  *
00636  *  COMMUNICATION:  None++.
00637  *
00638  *  \param  instance                 (In)     Mesh instance containing the
00639  *                                            partition.
00640  *  \param  partition                (In)     The partition being queried.
00641  *  \param  part                     (In)     The part being queried.
00642  *  \param  entity_type              (In)     Entity type of the copied
00643  *                                            entities;
00644  *                                            may be iBase_ALL_TYPES.
00645  *  \param  num_part_nbors           (Out)    Number of parts neighboring
00646  *                                            the given part.
00647  *  \param  nbor_part_ids            (In/Out) Array of part IDs for
00648  *                                            part neighbors of part.
00649  *  \param  nbor_part_ids_allocated  (In/Out) Allocated size of nbor_part_ids
00650  *                                            array.
00651  *  \param  nbor_part_ids_size       (Out)    Occupied size of nbor_part_ids
00652  *                                            array.
00653  *  \param  err                      (Out)    Error code.
00654  */
00655 void iMeshP_getPartNbors( iMesh_Instance instance,
00656                           const iMeshP_PartitionHandle partition,
00657                           const iMeshP_PartHandle part,
00658                           int entity_type,
00659                           int* num_part_nbors,
00660                           iMeshP_Part** nbor_part_ids,
00661                           int* nbor_part_ids_allocated,
00662                           int* nbor_part_ids_size,
00663                           int* err );
00664 
00665 /** \brief Return the parts that neighbor given parts.
00666  *
00667  *  Given a partition handle, an array of part handles, and an entity type,
00668  *  return the part IDs of parts that neighbor the given parts
00669  *  (i.e., that (1) have copies of entities of the given entity type owned by
00670  *  the given part or (2) own entities of the given entity type that are
00671  *  copied on the given part).
00672  *
00673  *  COMMUNICATION:  None++.
00674  *
00675  *  \param  instance                 (In)     Mesh instance containing the
00676  *                                            partition.
00677  *  \param  partition                (In)     The partition being queried.
00678  *  \param  parts                    (In)     The parts being queried.
00679  *  \param  parts_size               (In)     The number of parts being queried.
00680  *  \param  entity_type              (In)     Entity type of the copied
00681  *                                            entities;
00682  *                                            may be iBase_ALL_TYPES.
00683  *  \param  num_part_nbors           (In/Out) Array of values specifying the
00684  *                                            number of part neighbors for
00685  *                                            each part in parts.
00686  *  \param  num_part_nbors_allocated (In/Out) Allocated size of num_part_nbors
00687  *                                            array.
00688  *  \param  num_part_nbors_size      (Out)    Occupied size of num_part_nbors
00689  *                                            array.
00690  *  \param  nbor_part_ids            (In/Out) Array of part IDs for
00691  *                                            part neighbors of part.
00692  *  \param  nbor_part_ids_allocated  (In/Out) Allocated size of nbor_part_ids
00693  *                                            array.
00694  *  \param  nbor_part_ids_size       (Out)    Occupied size of nbor_part_ids
00695  *                                            array.
00696  *  \param  err                      (Out)    Error code.
00697  */
00698 void iMeshP_getPartNborsArr( iMesh_Instance instance,
00699                              const iMeshP_PartitionHandle partition,
00700                              const iMeshP_PartHandle* parts,
00701                              const int parts_size,
00702                              int entity_type,
00703                              int** num_part_nbors,
00704                              int* num_part_nbors_allocated,
00705                              int* num_part_nbors_size,
00706                              iMeshP_Part** nbor_part_ids,
00707                              int* nbor_part_ids_allocated,
00708                              int* nbor_part_ids_size,
00709                              int* err );
00710 
00711 /** \brief Return the number of entities on a part boundary.
00712  *
00713  *  Given a partition handle, a part handle, an entity type and topology, and a
00714  *  target part ID, return the number of entities of the given type and/or
00715  *  topology on the part boundary shared with the target part.
00716  *
00717  *  COMMUNICATION:  None.
00718  *
00719  *  \param  instance          (In)  Mesh instance containing the partition.
00720  *  \param  partition         (In)  The partition being queried.
00721  *  \param  part              (In)  The part being queried.
00722  *  \param  entity_type       (In)  Entity type of the boundary entities;
00723  *                                  may be iBase_ALL_TYPES.
00724  *  \param  entity_topology   (In)  Entity topology of the boundary entities;
00725  *                                  may be iMesh_ALL_TOPOLOGIES.
00726  *  \param  target_part_id    (In)  Part ID with which part is sharing
00727  *                                  the boundary entities; may be
00728  *                                  iMeshP_ALL_PARTS.
00729  *  \param  num_entities      (Out) Number of part boundary entities shared
00730  *                                  by part and target_part_id.
00731  *  \param  err               (Out) Error code.
00732  */
00733 void iMeshP_getNumPartBdryEnts( iMesh_Instance instance,
00734                                 const iMeshP_PartitionHandle partition,
00735                                 const iMeshP_PartHandle part,
00736                                 int entity_type,
00737                                 int entity_topology,
00738                                 iMeshP_Part target_part_id,
00739                                 int* num_entities,
00740                                 int* err );
00741 
00742 /** \brief Return the entity handles of entities on a part boundary.
00743  *
00744  *  Given a partition handle, a part handle, an entity type and topology, and a
00745  *  target part ID, return the entity handles of entities of the given type
00746  *  and/or topology on the part boundary shared with the target part.
00747  *
00748  *  COMMUNICATION:  None.
00749  *
00750  *  \param  instance                 (In)     Mesh instance containing the
00751  *                                            partition.
00752  *  \param  partition                (In)     The partition being queried.
00753  *  \param  part                     (In)     The part being queried.
00754  *  \param  entity_type              (In)     Entity type of the boundary
00755  *                                            entities;
00756  *                                            may be iBase_ALL_TYPES.
00757  *  \param  entity_topology          (In)     Entity topology of the boundary
00758  *                                            entities;
00759  *                                            may be iMesh_ALL_TOPOLOGIES.
00760  *  \param  target_part_id           (In)     Part ID with which part
00761  *                                            is sharing the boundary entities;
00762  *                                            may be iMeshP_ALL_PARTS.
00763  *  \param  entities                 (In/Out) Array of entity handles for
00764  *                                            entities on the part boundary
00765  *                                            between part and
00766  *                                            target_part_id.
00767  *  \param  entities_allocated       (In/Out) Allocated size of entities
00768  *                                            array.
00769  *  \param  entities_size            (Out)    Occupied size of entities
00770  *                                            array.
00771  *  \param  err                      (Out)    Error code.
00772  */
00773 void iMeshP_getPartBdryEnts( iMesh_Instance instance,
00774                              const iMeshP_PartitionHandle partition,
00775                              const iMeshP_PartHandle part,
00776                              int entity_type,
00777                              int entity_topology,
00778                              iMeshP_Part target_part_id,
00779                              iBase_EntityHandle** entities,
00780                              int* entities_allocated,
00781                              int* entities_size,
00782                              int* err );
00783 
00784 /** \brief Initialize an iterator over a specified part boundary.
00785  *
00786  *  Given a partition handle, a part handle, and a
00787  *  target part ID, return an iterator over all entities of a given
00788  *  entity type and topology along
00789  *  the part boundary shared with the target part.
00790  *  Iterator functionality for getNext, reset, and end is
00791  *  provided through the regular iMesh iterator functions
00792  *  iMesh_getNextEntIter, iMesh_resetEntIter, and iMesh_endEntIter,
00793  *  respectively.
00794  *
00795  *  COMMUNICATION:  None.
00796  *
00797  *  \param  instance          (In)  Mesh instance containing the partition.
00798  *  \param  partition         (In)  The partition being queried.
00799  *  \param  part              (In)  The part being queried.
00800  *  \param  entity_type       (In)  Entity type of the boundary entities;
00801  *                                  may be iBase_ALL_TYPES.
00802  *  \param  entity_topology   (In)  Entity topology of the boundary entities;
00803  *                                  may be iMesh_ALL_TOPOLOGIES.
00804  *  \param  target_part_id    (In)  Part ID with which part is sharing
00805  *                                  the boundary entities; may be
00806  *                                  iMeshP_ALL_PARTS.
00807  *  \param  entity_iterator   (Out) Iterator returned by the function.
00808  *  \param  err               (Out) Error code.
00809  */
00810 void iMeshP_initPartBdryEntIter( iMesh_Instance instance,
00811                                  const iMeshP_PartitionHandle partition,
00812                                  const iMeshP_PartHandle part,
00813                                  int entity_type,
00814                                  int entity_topology,
00815                                  iMeshP_Part target_part_id,
00816                                  iBase_EntityIterator* entity_iterator,
00817                                  int* err );
00818 
00819 /** \brief Initialize an array iterator over a specified part boundary.
00820  *
00821  *  Given a partition handle, a part handle, and a
00822  *  target part ID, return an array iterator over all entities of a given
00823  *  entity type and topology along
00824  *  the part boundary shared with the target part.
00825  *  Iterator functionality for getNext, reset, and end is
00826  *  provided through the regular iMesh iterator functions
00827  *  iMesh_getNextEntArrIter, iMesh_resetEntArrIter, and iMesh_endEntArrIter,
00828  *  respectively.
00829  *
00830  *  COMMUNICATION:  None.
00831  *
00832  *  \param  instance          (In)  Mesh instance containing the partition.
00833  *  \param  partition         (In)  The partition being queried.
00834  *  \param  part              (In)  The part being queried.
00835  *  \param  entity_type       (In)  Entity type of the boundary entities;
00836  *                                  may be iBase_ALL_TYPES.
00837  *  \param  entity_topology   (In)  Entity topology of the boundary entities;
00838  *                                  may be iMesh_ALL_TOPOLOGIES.
00839  *  \param  array_size        (In)  Size of chunks of handles returned for
00840  *                                  each value of the iterator.
00841  *  \param  target_part_id    (In)  Part ID with which part is sharing
00842  *                                  the boundary entities; may be
00843  *                                  iMeshP_ALL_PARTS.
00844  *  \param  entity_iterator   (Out) Iterator returned by the function.
00845  *  \param  err               (Out) Error code.
00846  */
00847 void iMeshP_initPartBdryEntArrIter( iMesh_Instance instance,
00848                                     const iMeshP_PartitionHandle partition,
00849                                     const iMeshP_PartHandle part,
00850                                     int entity_type,
00851                                     int entity_topology,
00852                                     int array_size,
00853                                     iMeshP_Part target_part_id,
00854                                     iBase_EntityArrIterator* entity_iterator,
00855                                     int* err );
00856 
00857 /*------------------------------------------------------------------------*/
00858 /*                        Parts and Sets                                  */
00859 /*------------------------------------------------------------------------*/
00860 
00861 /**  \brief Return the number of entities of a given type in both a part and an entity set.
00862  *
00863  *  Given a part handle, an entity set handle, and an entity type, return
00864  *  the number of entities of the given type that are in BOTH the given
00865  *  part AND the given entity set.
00866  *  This function is similar to iMesh_getNumOfType, but it also restricts
00867  *  the returned data with respect to its existence in the given part.
00868  *
00869  *  COMMUNICATION:  None.
00870  *
00871  *  \param  instance          (In)  Mesh instance containing the partition.
00872  *  \param  partition         (In)  The partition being queried.
00873  *  \param  part              (In)  The part being queried.
00874  *  \param  entity_set        (In)  Entity set handle for the entity set
00875  *                                  being queried; may be the root set.
00876  *  \param  entity_type       (In)  Entity type of the boundary entities;
00877  *                                  may be iBase_ALL_TYPES.
00878  *  \param  num_type          (Out) Number of entities of entity_type in
00879  *                                  both part and entity_set.
00880  *  \param  err               (Out) Error code.
00881  */
00882 void iMeshP_getNumOfType( iMesh_Instance instance,
00883                           const iMeshP_PartitionHandle partition,
00884                           const iMeshP_PartHandle part,
00885                           const iBase_EntitySetHandle entity_set,
00886                           int entity_type,
00887                           int* num_type,
00888                           int* err );
00889 
00890 /**  \brief Return the number of entities of a given topology in both a part and an entity set.
00891  *
00892  *  Given a part handle, an entity set handle, and an entity topology, return
00893  *  the number of entities of the given topology that are in BOTH the given
00894  *  part AND the given entity set.
00895  *  This function is similar to iMesh_getNumOfTopo, but it also restricts
00896  *  the returned data with respect to its existence in the given part.
00897  *
00898  *  COMMUNICATION:  None.
00899  *
00900  *  \param  instance          (In)  Mesh instance containing the partition.
00901  *  \param  partition         (In)  The partition being queried.
00902  *  \param  part              (In)  The part being queried.
00903  *  \param  entity_set        (In)  Entity set handle for the entity set
00904  *                                  being queried; may be the root set.
00905  *  \param  entity_topology   (In)  Entity topology of the boundary entities;
00906  *                                  may be iMesh_ALL_TOPOLOGIES.
00907  *  \param  num_topo          (Out) Number of entities of entity_topology in
00908  *                                  both part and entity_set.
00909  *  \param  err               (Out) Error code.
00910  */
00911 void iMeshP_getNumOfTopo( iMesh_Instance instance,
00912                           const iMeshP_PartitionHandle partition,
00913                           const iMeshP_PartHandle part,
00914                           const iBase_EntitySetHandle entity_set,
00915                           int entity_topology,
00916                           int* num_topo,
00917                           int* err );
00918 
00919 /**\brief Get indexed representation of mesh or subset of mesh
00920  *
00921  * Given part handle and an entity set and optionally a type or topology,
00922  * for all entities that are in BOTH the part and the entity set, return:
00923  * - The entities in the part and set of the specified type or topology
00924  * - The entities adjacent to those entities with a specified
00925  *    type, as a list of unique handles.
00926  * - For each entity in the first list, the adjacent entities,
00927  *    specified as indices into the second list.
00928  *
00929  *  COMMUNICATION:  None.
00930  *
00931  *\param  instance                (In)     Mesh instance containing the
00932  *                                         partition.
00933  *\param  partition               (In)     The partition being queried.
00934  *\param  part                    (In)     The part being queried.
00935  *\param entity_set_handle        (In)     The set being queried
00936  *\param entity_type_requestor    (In)     If not iBase_ALL_TYPES, act only
00937  *                                         on the subset of entities with
00938  *                                         the specified type.
00939  *\param entity_topology_requestor (In)    If not iMesh_ALL_TOPOLOGIES, act
00940  *                                         only on the subset of entities with
00941  *                                         the specified topology.
00942  *\param entity_type_requested    (In)     The type of the adjacent entities
00943  *                                         to return.
00944  *\param entity_handles           (In/Out) The handles of the (non-strict)
00945  *                                         subset of the union of the part
00946  *                                         and entity set, and the optional
00947  *                                         type and topology filtering
00948  *                                         arguments.
00949  *\param adj_entity_handles       (In/Out) The union of the entities of type
00950  *                                         'requested_entity_type' adjacent
00951  *                                         to each entity in 'entity_handles'.
00952  *\param adj_entity_indices       (In/Out) For each entity in 'entity_handles',
00953  *                                         the adjacent entities of type
00954  *                                         'entity_type_requested', specified as
00955  *                                         indices into 'adj_entity_handles'.
00956  *                                         The indices are concatenated into a
00957  *                                         single array in the order of the
00958  *                                         entity handles in 'entity_handles'.
00959  *\param offset                   (In/Out) For each entity in the
00960  *                                         corresponding position in
00961  *                                         'entity_handles', the position
00962  *                                         in 'adj_entity_indices' at which
00963  *                                         values for that entity are stored.
00964  */
00965 void iMeshP_getAdjEntIndices( iMesh_Instance instance,
00966                               iMeshP_PartitionHandle partition,
00967                               iMeshP_PartHandle part,
00968                               iBase_EntitySetHandle entity_set_handle,
00969                               int entity_type_requestor,
00970                               int entity_topology_requestor,
00971                               int entity_type_requested,
00972                               iBase_EntityHandle** entity_handles,
00973                               int* entity_handles_allocated,
00974                               int* entity_handles_size,
00975                               iBase_EntityHandle** adj_entity_handles,
00976                               int* adj_entity_handles_allocated,
00977                               int* adj_entity_handles_size,
00978                               int** adj_entity_indices,
00979                               int* adj_entity_indices_allocated,
00980                               int* adj_entity_indices_size,
00981                               int** offset,
00982                               int* offset_allocated,
00983                               int* offset_size,
00984                               int* err );
00985 
00986 /** \brief Return entities in a both given part and entity set.
00987  *
00988  *  Given an entity set handle
00989  *  and a part handle, return entity handles for entities
00990  *  that are in both the part and the entity set.
00991  *  This function is similar to iMesh_getEntities, but it also restricts
00992  *  the returned data with respect to its existence in the given part.
00993  *
00994  *  COMMUNICATION:  None.
00995  *
00996  *  \param  instance                 (In)     Mesh instance containing the
00997  *                                            partition.
00998  *  \param  partition                (In)     The partition being queried.
00999  *  \param  part                     (In)     The part being queried.
01000  *  \param  entity_set               (In)     Entity set handle for the
01001  *                                            entity set being queried;
01002  *                                            may be the root set.
01003  *  \param  entity_type              (In)     Entity type of the
01004  *                                            entities;
01005  *                                            may be iBase_ALL_TYPES.
01006  *  \param  entity_topology          (In)     Entity topology of the
01007  *                                            entities;
01008  *                                            may be iMesh_ALL_TOPOLOGIES.
01009  *  \param  entities                 (In/Out) Array of entity handles for
01010  *                                            entities in both part
01011  *                                            and entity_set.
01012  *  \param  entities_allocated       (In/Out) Allocated size of entities.
01013  *  \param  entities_size            (Out)    Occupied size of entities.
01014  *  \param  err                      (Out)    Error code.
01015  */
01016 void iMeshP_getEntities( iMesh_Instance instance,
01017                          const iMeshP_PartitionHandle partition,
01018                          const iMeshP_PartHandle part,
01019                          const iBase_EntitySetHandle entity_set,
01020                          int entity_type,
01021                          int entity_topology,
01022                          iBase_EntityHandle** entities,
01023                          int* entities_allocated,
01024                          int* entities_size,
01025                          int* err );
01026 
01027 /** \brief Return entities adjacent to entities in a given part and entity set.
01028  *
01029  *  Given an entity set handle
01030  *  and a part handle, return entities adjacent (with respect to a given
01031  *  entity type and/or topology) to entities
01032  *  that are in both the part and the entity set.
01033  *  This function is similar to iMesh_getAdjEntities, but it also restricts
01034  *  the returned data with respect to its existence in the given part.
01035  *  If a non-root entity set is specified, the function also returns
01036  *  flags indicating whether each adjacent entity
01037  *  is in the entity set; (*in_entity_set)[i]=1 indicates that adjacent entity
01038  *  (*adj_entities)[i] is in the specified entity set.
01039  *  Array entry offset[i] stores the index of first adjacent entity to
01040  *  entity i.
01041  *
01042  *  COMMUNICATION:  None.
01043  *
01044  *  \param  instance                     (In)     Mesh instance containing the
01045  *                                                partition.
01046  *  \param  partition                    (In)     The partition being queried.
01047  *  \param  part                         (In)     The part being queried.
01048  *  \param  entity_set                   (In)     Entity set handle for the
01049  *                                                entity set being queried;
01050  *                                                may be the root set.
01051  *  \param  entity_type_requestor        (In)     Return entities adjacent to
01052  *                                                entities of this type;
01053  *                                                may be iBase_ALL_TYPES.
01054  *  \param  entity_topology_requestor    (In)     Return entities adjacent to
01055  *                                                entities of this topology;
01056  *                                                may be iMesh_ALL_TOPOLOGIES.
01057  *  \param  entity_type_requested        (In)     Return adjacent entities of
01058  *                                                this type;
01059  *                                                may be iBase_ALL_TYPES.
01060  *  \param  adj_entities                 (In/Out) Array of adjacent entity
01061  *                                                handles returned.
01062  *  \param  adj_entities_allocated       (In/Out) Allocated size of
01063  *                                                adj_entities.
01064  *  \param  adj_entities_size            (Out)    Occupied size of
01065  *                                                adj_entities.
01066  *  \param  offset                       (In/Out) Array of offsets returned.
01067  *  \param  offset_allocated             (In/Out) Allocated size of offset.
01068  *  \param  offset_size                  (Out)    Occupied size of offset.
01069  *  \param  in_entity_set                (In/Out) Array of flags returned if
01070  *                                                non-root entity set was input;
01071  *                                                (*in_entity_set)[i]=1
01072  *                                                indicates
01073  *                                                (*adj_entities)[i]
01074  *                                                is in the entity set.
01075  *  \param  in_entity_set_allocated      (In/Out) Allocated size of
01076  *                                                in_entity_set.
01077  *  \param  in_entity_set_size           (Out)    Occupied size of
01078  *                                                in_entity_set.
01079  *  \param  err                          (Out)    Error code.
01080  */
01081 void iMeshP_getAdjEntities( iMesh_Instance instance,
01082                             const iMeshP_PartitionHandle partition,
01083                             const iMeshP_PartHandle part,
01084                             const iBase_EntitySetHandle entity_set,
01085                             int entity_type_requestor,
01086                             int entity_topology_requestor,
01087                             int entity_type_requested,
01088                             iBase_EntityHandle** adj_entities,
01089                             int* adj_entities_allocated,
01090                             int* adj_entities_size,
01091                             int** offset,
01092                             int* offset_allocated,
01093                             int* offset_size,
01094                             int** in_entity_set,
01095                             int* in_entity_set_allocated,
01096                             int* in_entity_set_size,
01097                             int* err );
01098 
01099 /** \brief Create an entity iterator for a given part and entity set.
01100 
01101  *  Given a local part and an entity set, return an iterator over the
01102  *  entities of the requested type and topology that are in both the
01103  *  part and the entity set.
01104  *  Iterator functionality for getNext, reset, and end is
01105  *  provided through the regular iMesh iterator functions
01106  *  iMesh_getNextEntIter, iMesh_resetEntIter, and iMesh_endEntIter,
01107  *  respectively.
01108  *
01109  *  COMMUNICATION:  None.
01110  *
01111  *  \param  instance                     (In)  Mesh instance containing the
01112  *                                             partition.
01113  *  \param  partition                    (In)  The partition being queried.
01114  *  \param  part                         (In)  The part being queried.
01115  *  \param  entity_set                   (In)  Entity set handle for the
01116  *                                             entity set being queried.
01117  *  \param  requested_entity_type        (In)  Type of entities to include in
01118  *                                             the iterator.
01119  *  \param  requested_entity_topology    (In)  Topology of entities to include
01120  *                                             in the iterator.
01121  *  \param  entity_iterator              (Out) Iterator returned from function.
01122  *  \param  err                          (Out) Error code.
01123  */
01124 void iMeshP_initEntIter( iMesh_Instance instance,
01125                          const iMeshP_PartitionHandle partition,
01126                          const iMeshP_PartHandle part,
01127                          const iBase_EntitySetHandle entity_set,
01128                          const int requested_entity_type,
01129                          const int requested_entity_topology,
01130                          iBase_EntityIterator* entity_iterator,
01131                          int* err );
01132 
01133 /** \brief Create an entity array iterator for a given part and entity set.
01134 
01135  *  Given a local part and an entity set, return an array iterator over the
01136  *  entities of the requested type and topology that are in both the
01137  *  part and the entity set.
01138  *  Iterator functionality for getNext, reset, and end is
01139  *  provided through the regular iMesh iterator functions
01140  *  iMesh_getNextEntArrIter, iMesh_resetEntArrIter, and iMesh_endEntArrIter,
01141  *  respectively.
01142  *
01143  *  COMMUNICATION:  None.
01144  *
01145  *  \param  instance                     (In)  Mesh instance containing the
01146  *                                             partition.
01147  *  \param  partition                    (In)  The partition being queried.
01148  *  \param  part                         (In)  The part being queried.
01149  *  \param  entity_set                   (In)  Entity set handle for the
01150  *                                             entity set being queried.
01151  *  \param  requested_entity_type        (In)  Type of entities to include in
01152  *                                             the iterator.
01153  *  \param  requested_entity_topology    (In)  Topology of entities to include
01154  *                                             in the iterator.
01155  *  \param  requested_array_size         (In)  The number of handles returned
01156  *                                             in each value of the iterator.
01157  *  \param  entArr_iterator              (Out) Iterator returned from function.
01158  *  \param  err                          (Out) Error code.
01159  */
01160 void iMeshP_initEntArrIter( iMesh_Instance instance,
01161                             const iMeshP_PartitionHandle partition,
01162                             const iMeshP_PartHandle part,
01163                             const iBase_EntitySetHandle entity_set,
01164                             const int requested_entity_type,
01165                             const int requested_entity_topology,
01166                             const int requested_array_size,
01167                             iBase_EntityArrIterator* entArr_iterator,
01168                             int* err );
01169 
01170 /*------------------------------------------------------------------------*/
01171 /*------------------------------------------------------------------------*/
01172 /*                           Entity Functionality                         */
01173 /*------------------------------------------------------------------------*/
01174 /*------------------------------------------------------------------------*/
01175 
01176 /** \brief  Return the part ID of the part owning an entity.
01177  *
01178  *  Given an entity handle and a partition handle, return the part ID
01179  *  of the part that owns the entity.
01180  *  Return an error code if an entity is not in the partition.
01181  *
01182  *  COMMUNICATION:  None++.
01183  *
01184  *  \param  instance                     (In)  Mesh instance containing the
01185  *                                             partition.
01186  *  \param  partition                    (In)  The partition being queried.
01187  *  \param  entity                       (In)  Entity whose owning part is to be
01188  *                                             returned.
01189  *  \param  part_id                      (Out) Part ID of the part owning
01190  *                                             the entity.
01191  *  \param  err                          (Out) Error code.
01192  */
01193 void iMeshP_getEntOwnerPart( iMesh_Instance instance,
01194                              const iMeshP_PartitionHandle partition,
01195                              const iBase_EntityHandle entity,
01196                              iMeshP_Part* part_id,
01197                              int* err );
01198 
01199 /** \brief  Return the part IDs of the parts owning the given entities.
01200  *
01201  *  Given an array of entity handles and a partition handle, return for each
01202  *  entity handle the part ID of the part that owns the entity.
01203  *  Return an error code if an entity is not in the partition.
01204  *
01205  *  COMMUNICATION:  None++.
01206  *
01207  *  \param  instance              (In)     Mesh instance containing the
01208  *                                         partition.
01209  *  \param  partition             (In)     The partition being queried.
01210  *  \param  entities              (In)     Entity whose owning part is to be
01211  *                                         returned.
01212  *  \param  entities_size         (In)     Number of entities in
01213  *                                         entities array.
01214  *  \param  part_ids              (Out)    Part IDs of the parts owning
01215  *                                         the entities.
01216  *  \param  part_ids_allocated    (In/Out) Allocated size of part_ids array.
01217  *  \param  part_ids_size         (Out)    Occupied size of part_ids array.
01218  *  \param  err                   (Out)    Error code.
01219  */
01220 void iMeshP_getEntOwnerPartArr( iMesh_Instance instance,
01221                                 const iMeshP_PartitionHandle partition,
01222                                 const iBase_EntityHandle* entities,
01223                                 const int entities_size,
01224                                 iMeshP_Part** part_ids,
01225                                 int* part_ids_allocated,
01226                                 int* part_ids_size,
01227                                 int* err );
01228 
01229 /** \brief Test for entity ownership with respect to a part.
01230  *
01231  *  Given a partition handle, a part handle, and an entity handle, return a
01232  *  flag indicating whether the entity is owned by the part.
01233  *
01234  *  COMMUNICATION:  None.
01235  *
01236  *  \param  instance             (In)  Mesh instance containing the partition.
01237  *  \param  partition            (In)  The partition being queried.
01238  *  \param  part                 (In)  The part being queried.
01239  *  \param  entity               (In)  Entity whose ownership is being tested.
01240  *  \param  is_owner             (Out) Flag indicating whether the given part
01241  *                                     is the owner of the given entity.
01242  *  \param  err                  (Out) Error code.
01243  */
01244 void iMeshP_isEntOwner( iMesh_Instance instance,
01245                         const iMeshP_PartitionHandle partition,
01246                         const iMeshP_PartHandle part,
01247                         const iBase_EntityHandle entity,
01248                         int* is_owner,
01249                         int* err );
01250 
01251 /** \brief Test for entity ownership of many entities with respect to a part.
01252  *
01253  *  Given a partition handle, a part handle, and an array of entity handles,
01254  *  return for each entity handle a flag indicating whether the entity
01255  *  is owned by the part.
01256  *
01257  *  COMMUNICATION:  None.
01258  *
01259  *  \param  instance                 (In)     Mesh instance containing the
01260  *                                            partition.
01261  *  \param  partition                (In)     The partition being queried.
01262  *  \param  part                     (In)     The part being queried.
01263  *  \param  entities                 (In)     Entities whose ownership is
01264  *                                            being tested.
01265  *  \param  entities_size            (In)     Number of entity handles in
01266  *                                            entities.
01267  *  \param  is_owner                 (Out)    Flag for each entity indicating
01268  *                                            whether the given part is the
01269  *                                            owner of the given entity.
01270  *  \param  is_owner_allocated       (In/Out) Allocated size of is_owner array.
01271  *  \param  is_owner_size            (Out)    Occupied size of is_owner array.
01272  *  \param  err                      (Out)    Error code.
01273  */
01274 void iMeshP_isEntOwnerArr( iMesh_Instance instance,
01275                            const iMeshP_PartitionHandle partition,
01276                            const iMeshP_PartHandle part,
01277                            const iBase_EntityHandle* entities,
01278                            const int entities_size,
01279                            int** is_owner,
01280                            int* is_owner_allocated,
01281                            int* is_owner_size,
01282                            int* err );
01283 
01284 /** \brief Return entity status (Internal, boundary, ghost).
01285  *
01286  *  Given a partition handle, a part handle, and an entity handle, return a
01287  *  flag indicating whether the entity is strictly internal, is on a
01288  *  part boundary, or is a ghost with respect to the given part.
01289  *  The returned value is a member of the iMeshP_EntStatus enumerated type.
01290  *
01291  *  COMMUNICATION:  None.
01292  *
01293  *  \param  instance             (In)  Mesh instance containing the partition.
01294  *  \param  partition            (In)  The partition being queried.
01295  *  \param  part                 (In)  The part being queried.
01296  *  \param  entity               (In)  Entity whose status is being tested.
01297  *  \param  par_status           (Out) Value indicating the status of the
01298  *                                     is the entity with respect to the part.
01299  *  \param  err                  (Out) Error code.
01300  */
01301 void iMeshP_getEntStatus( iMesh_Instance instance,
01302                           const iMeshP_PartitionHandle partition,
01303                           const iMeshP_PartHandle part,
01304                           const iBase_EntityHandle entity,
01305                           int* par_status,
01306                           int* err );
01307 
01308 /** \brief Return entity status (Internal, boundary, ghost).
01309  *
01310  *  Given a partition handle, a part handle, and an array of entity handles,
01311  *  return for each entity handle a flag indicating whether the entity is
01312  *  strictly internal, is on a part boundary, or is a ghost with respect
01313  *  to the given part.
01314  *  The returned value is a member of the iMeshP_EntStatus enumerated type.
01315  *
01316  *  COMMUNICATION:  None.
01317  *
01318  *  \param  instance                (In)     Mesh instance containing the
01319  *                                           partition.
01320  *  \param  partition               (In)     The partition being queried.
01321  *  \param  part                    (In)     The part being queried.
01322  *  \param  entities                (In)     Entities whose status is
01323  *                                           being tested.
01324  *  \param  entities_size           (In)     Number of entity handles in
01325  *                                           entities.
01326  *  \param  par_status              (Out)    Value for each entity indicating
01327  *                                           the status of the entity with
01328  *                                           respect to the part.
01329  *  \param  par_status_allocated    (In/Out) Allocated size of par_status array.
01330  *  \param  par_status_size         (Out)    Occupied size of par_status array.
01331  *  \param  err                     (Out)    Error code.
01332  */
01333 
01334 void iMeshP_getEntStatusArr( iMesh_Instance instance,
01335                              const iMeshP_PartitionHandle partition,
01336                              const iMeshP_PartHandle part,
01337                              const iBase_EntityHandle* entities,
01338                              const int entities_size,
01339                              int** par_status, /* enum iMeshP_EntStatus */
01340                              int* par_status_allocated,
01341                              int* par_status_size,
01342                              int* err );
01343 
01344 /** \brief Return the number of copies of an entity that exist in the partition.
01345  *
01346  *  Given a partition handle and an entity handle, return the number
01347  *  of copies of the entity in the partition.
01348  *  If the given entity is an owned entity or boundary entity,
01349  *  the number of copies will be complete.
01350  *  If the given entity is a ghost entity, the number of copies will be two
01351  *  (the ghost and its owner).
01352  *
01353  *  COMMUNICATION:  None++.
01354  *
01355  *  \param  instance             (In)  Mesh instance containing the partition.
01356  *  \param  partition            (In)  The partition being queried.
01357  *  \param  entity               (In)  Entity whose copy info is requested.
01358  *  \param  num_copies_ent       (Out) Number of copies of the entity that
01359  *                                     exist in the partition.
01360  *  \param  err                  (Out) Error code.
01361  */
01362 void iMeshP_getNumCopies( iMesh_Instance instance,
01363                           const iMeshP_PartitionHandle partition,
01364                           const iBase_EntityHandle entity,
01365                           int* num_copies_ent,
01366                           int* err );
01367 
01368 /** \brief Return the part IDs of parts having copies of a given entity.
01369  *
01370  *  Given a partition handle and an entity handle, return the part IDs
01371  *  of copies of the entity in the partition.
01372  *  If the given entity is an owned entity or boundary entity,
01373  *  the number of copies considered will be complete.
01374  *  If the given entity is a ghost entity, the number of copies considered
01375  *  will be two (the ghost and its owner).
01376  *
01377  *  COMMUNICATION:  None++.
01378  *
01379  *  \param  instance                (In)     Mesh instance containing the
01380  *                                           partition.
01381  *  \param  partition               (In)     The partition being queried.
01382  *  \param  entity                  (In)     Entity whose copy info
01383  *                                           is requested.
01384  *  \param  part_ids                (Out)    Part IDs of parts having copies
01385  *                                           of the given entity.
01386  *  \param  part_ids_allocated      (In/Out) Allocated size of part_ids array.
01387  *  \param  part_ids_size           (Out)    Occupied size of part_ids array.
01388  *  \param  err                     (Out)    Error code.
01389  */
01390 void iMeshP_getCopyParts( iMesh_Instance instance,
01391                           const iMeshP_PartitionHandle partition,
01392                           const iBase_EntityHandle entity,
01393                           iMeshP_Part** part_ids,
01394                           int* part_ids_allocated,
01395                           int* part_ids_size,
01396                           int* err );
01397 
01398 /**  \brief Get (remote) entity handles of copies of a given entity.
01399  *
01400  *  Given a partition handle and an entity handle, return (remote) entity
01401  *  handles and part IDs of all copies of the entity.
01402  *  If the given entity is an owned entity or boundary entity,
01403  *  the number of copies considered will be complete.
01404  *  If the given entity is a ghost entity, the number of copies considered
01405  *  will be two (the ghost and its owner).
01406  *
01407  *  COMMUNICATION:  None++.
01408  *
01409  *  \param  instance                (In)     Mesh instance containing the
01410  *                                           partition.
01411  *  \param  partition               (In)     The partition being queried.
01412  *  \param  entity                  (In)     Entity whose copy info
01413  *                                           is requested.
01414  *  \param  part_ids                (Out)    Part IDs of parts having copies
01415  *                                           of the given entity.
01416  *  \param  part_ids_allocated      (In/Out) Allocated size of part_ids array.
01417  *  \param  part_ids_size           (Out)    Occupied size of part_ids array.
01418  *  \param  copies                  (Out)    (Remote) entity handles of the
01419  *                                           entity copies.
01420  *  \param  copies_allocated        (In/Out) Allocated size of copies.
01421  *  \param  copies_size             (Out)    Occupied size of copies.
01422  *  \param  err                     (Out)    Error code.
01423  */
01424 void iMeshP_getCopies( iMesh_Instance instance,
01425                        const iMeshP_PartitionHandle partition,
01426                        const iBase_EntityHandle entity,
01427                        iMeshP_Part** part_ids,
01428                        int* part_ids_allocated,
01429                        int* part_ids_size,
01430                        iBase_EntityHandle** copies,
01431                        int* copies_allocated,
01432                        int* copies_size,
01433                        int* err );
01434 
01435 /**  \brief Get the entity handle of a copy of a given entity in a given part.
01436  *
01437  *  Given a partition handle, an entity handle and a part ID,
01438  *  return the (remote) entity handle of the copy of the entity in that part.
01439  *  Return an error if the entity does not exist in the specified part.
01440  *
01441  *  COMMUNICATION:  None++.
01442  *
01443  *  \param  instance                (In)  Mesh instance containing the
01444  *                                        partition.
01445  *  \param  partition               (In)  The partition being queried.
01446  *  \param  entity                  (In)  Entity whose copy info
01447  *                                        is requested.
01448  *  \param  part_id                 (In)  Part ID of part whose copy
01449  *                                        of the given entity is requested.
01450  *  \param  copy_entity             (Out) (Remote) entity handle of the
01451  *                                        entity copy from the given part.
01452  *  \param  err                     (Out) Error code.
01453  */
01454 void iMeshP_getCopyOnPart( iMesh_Instance instance,
01455                            const iMeshP_PartitionHandle partition,
01456                            const iBase_EntityHandle entity,
01457                            const iMeshP_Part part_id,
01458                            iBase_EntityHandle* copy_entity,
01459                            int* err );
01460 
01461 /**  \brief Get the entity handle of a copy of a given entity in its owner part.
01462  *
01463  *  Given a partition handle and an entity handle, return the (remote)
01464  *  entity handle of the copy of the entity in its owner part.
01465  *
01466  *  COMMUNICATION:  None++.
01467  *
01468  *  \param  instance                (In)  Mesh instance containing the
01469  *                                        partition.
01470  *  \param  partition               (In)  The partition being queried.
01471  *  \param  entity                  (In)  Entity whose copy info
01472  *                                        is requested.
01473  *  \param  owner_part_id           (Out) Part ID of the entity's owner part.
01474  *  \param  owner_entity            (Out) (Remote) entity handle of the
01475  *                                        entity copy from the owner part.
01476  *  \param  err                     (Out) Error code.
01477  */
01478 void iMeshP_getOwnerCopy( iMesh_Instance instance,
01479                           const iMeshP_PartitionHandle partition,
01480                           const iBase_EntityHandle entity,
01481                           iMeshP_Part* owner_part_id,
01482                           iBase_EntityHandle* owner_entity,
01483                           int* err );
01484 
01485 /*------------------------------------------------------------------------*/
01486 /*------------------------------------------------------------------------*/
01487 /*-------                         COMMUNICATION                 ----------*/
01488 /*------------------------------------------------------------------------*/
01489 /*------------------------------------------------------------------------*/
01490 
01491 /**\brief  Wait for a specific iMeshP request to complete.
01492  *
01493  *  Given an iMeshP_RequestHandle, wait for the request to complete.
01494  *
01495  *  COMMUNICATION:  Blocking point-to-point.
01496  *
01497  *  \param  instance                (In)  Mesh instance containing the
01498  *                                        partition.
01499  *  \param  partition               (In)  The partition being queried.
01500  *  \param  request                 (In)  iMeshP request for whose completion
01501  *                                        we should wait.
01502  *  \param  err                     (Out) Error code.
01503  */
01504 void iMeshP_waitForRequest( iMesh_Instance instance,
01505                             const iMeshP_PartitionHandle partition,
01506                             iMeshP_RequestHandle request,
01507                             int* err );
01508 
01509 /**\brief  Wait for any of the specified iMeshP requests to complete.
01510  *
01511  *  Given an array of iMeshP_RequestHandles, wait for any one of the requests
01512  *  to complete.
01513  *
01514  *  COMMUNICATION:  Blocking point-to-point.
01515  *
01516  *  \param  instance                (In)  Mesh instance containing the
01517  *                                        partition.
01518  *  \param  partition               (In)  The partition being queried.
01519  *  \param  requests                (In)  iMeshP requests for which we wait
01520  *                                        until one request completes.
01521  *  \param  requests_size           (In)  Number of requests in requests.
01522  *  \param  index                   (Out) Index of the request that completed.
01523  *  \param  err                     (Out) Error code.
01524  */
01525 void iMeshP_waitForAnyRequest( iMesh_Instance instance,
01526                                const iMeshP_PartitionHandle partition,
01527                                iMeshP_RequestHandle* requests,
01528                                int requests_size,
01529                                int* index,
01530                                int* err );
01531 
01532 /**\brief  Wait for all of the specified iMeshP requests to complete.
01533  *
01534  *  Given an array of iMeshP_RequestHandles, wait for all of the requests
01535  *  to complete.
01536  *
01537  *  COMMUNICATION:  Blocking point-to-point.
01538  *
01539  *  \param  instance                (In)  Mesh instance containing the
01540  *                                        partition.
01541  *  \param  partition               (In)  The partition being queried.
01542  *  \param  requests                (In)  iMeshP requests for which we wait
01543  *                                        until completion.
01544  *  \param  requests_size           (In)  Number of requests in requests.
01545  *  \param  err                     (Out) Error code.
01546  */
01547 void iMeshP_waitForAllRequests( iMesh_Instance instance,
01548                                 const iMeshP_PartitionHandle partition,
01549                                 iMeshP_RequestHandle* requests,
01550                                 int requests_size,
01551                                 int* err );
01552 
01553 /**\brief  Wait for a specific request to complete; return entities received.
01554  *
01555  *  Given an iMeshP_RequestHandle, wait for the request to complete.  Return
01556  *  entities for which information was received.
01557  *
01558  *  COMMUNICATION:  Blocking point-to-point.
01559  *
01560  *  \param  instance                (In)     Mesh instance containing the
01561  *                                           partition.
01562  *  \param  partition               (In)     The partition being queried.
01563  *  \param  request                 (In)     iMeshP request for whose completion
01564  *                                           we should wait.
01565  *  \param  out_entities            (Out)    Entities for which information was
01566  *                                           received.
01567  *  \param  out_entities_allocated  (In/Out) Allocated size of out_entities.
01568  *  \param  out_entities_size       (Out)    Occupied size of out_entities.
01569  *  \param  err                     (Out)    Error code.
01570  */
01571 void iMeshP_waitForRequestEnt( iMesh_Instance instance,
01572                                const iMeshP_PartitionHandle partition,
01573                                iMeshP_RequestHandle request,
01574                                iBase_EntityHandle** out_entities,
01575                                int* out_entities_allocated,
01576                                int* out_entities_size,
01577                                int* err );
01578 
01579 /**\brief  Test whether a specific request has completed.
01580  *
01581  *  Given an iMeshP_RequestHandle, test whether the request has completed.
01582  *  This function will not wait until the request completes; it will only
01583  *  return the completion status (complete = 1 or 0).
01584  *
01585  *  COMMUNICATION:  None.
01586  *
01587  *  \param  instance                (In)  Mesh instance containing the
01588  *                                        partition.
01589  *  \param  partition               (In)  The partition being queried.
01590  *  \param  request                 (In)  iMeshP request for whose completion
01591  *                                        we should test.
01592  *  \param  completed               (Out) Flag indicating whether (1) or
01593  *                                        not (0) the given request has
01594  *                                        completed.
01595  *  \param  err                     (Out) Error code.
01596  */
01597 void iMeshP_testRequest( iMesh_Instance instance,
01598                          const iMeshP_PartitionHandle partition,
01599                          iMeshP_RequestHandle request,
01600                          int* completed,
01601                          int* err );
01602 
01603 /** \brief  Poll for outstanding requests.
01604  *
01605  *  Check for outstanding requests from other parts, handle any requests
01606  *  found, and return an array of requests that have been handled.  If
01607  *  the array has a size allocated already, then the implementation stops
01608  *  working when it has generated that many completed requests, even if there
01609  *  are more requests waiting.
01610  *
01611  *  COMMUNICATION:  non-blocking; point-to-point.
01612  *
01613  *  \param  instance                     (In)     Mesh instance containing the
01614  *                                                partition.
01615  *  \param  partition                    (In)     The partition being queried.
01616  *  \param  requests_completed           (Out)    Requests that were completed.
01617  *  \param  requests_completed_allocated (In/Out) Allocated size of
01618  *                                                requests_completed.
01619  *  \param  requests_completed_size      (Out)    Occupied size of
01620  *                                                requests_completed.
01621  *  \param  err                          (Out)    Error code.
01622  */
01623 void iMeshP_pollForRequests( iMesh_Instance instance,
01624                              iMeshP_PartitionHandle partition,
01625                              iMeshP_RequestHandle** requests_completed,
01626                              int* requests_completed_allocated,
01627                              int* requests_completed_size,
01628                              int* err );
01629 
01630 /*--------------------------------------------------------------------
01631   -------    Requests for off-processor mesh modification      -------
01632   --------------------------------------------------------------------*/
01633 
01634 /** \brief  Add entities to on-process and/or off-process parts.
01635  *
01636  *  Given a partition and a list of entities, add those entities to the
01637  *  target parts.  The entities can be added as copies or migrated entirely
01638  *  (i.e., change ownership of the entities)
01639  *  to the parts.  The entities' downward adjacencies are also copied and/or
01640  *  migrated as appropriate to support the entities.
01641  *  This function is a collective, non-blocking operation
01642  *  to be called by all processes in the partition's communicator.
01643  *  An iMeshP_RequestHandle is returned; any of the
01644  *  iMeshP_wait* functions can be used to block until the request is completed.
01645  *
01646  *  COMMUNICATION:  Collective.  Non-blocking.
01647  *
01648  *  \param  instance          (In)  Mesh instance containing the partition.
01649  *  \param  partition         (In)  Handle for the partition being queried.
01650  *  \param  entities          (In)  Entities to be sent.
01651  *  \param  entities_size     (In)  Number of entities to be sent.
01652  *  \param  target_part_ids   (In)  Array of size entities_size listing
01653  *                                  the parts to which the entities should
01654  *                                  be sent.
01655  *  \param  command_code      (In)  Flag indicating whether to migrate
01656  *                                  the entities or only make copies.
01657  *  \param  update_ghost      (In)  Flag indicating whether (1) or not (0)
01658  *                                  ghost copies of the entities should be
01659  *                                  updated with new owner information.
01660  *  \param  request           (Out) iMeshP RequestHandle returned; can be used
01661  *                                  for blocking until this send is complete.
01662  *  \param  err               (Out) Error code.
01663  */
01664 void iMeshP_exchEntArrToPartsAll( iMesh_Instance instance,
01665                                   const iMeshP_PartitionHandle partition,
01666                                   const iBase_EntityHandle* entities,
01667                                   const int entities_size,
01668                                   const iMeshP_Part* target_part_ids,
01669                                   int command_code,
01670                                   int update_ghost,
01671                                   iMeshP_RequestHandle* request,
01672                                   int* err );
01673 
01674 /** \brief Request in-migration of an entity and its upward adjacencies.
01675  *
01676  *  This function is a "pull" migration, where a part requests to become the
01677  *  owner of an entity that is owned by another part (so that the part has
01678  *  the right to modify the entity).  The requested
01679  *  entity must be on the part boundary and is identified by a local handle
01680  *  (i.e., an entity part-boundary copy).   This operation may require multiple
01681  *  rounds of communication, and at some times, certain entities may be
01682  *  locked (unavailable for local modification) while info about their
01683  *  remote copies is still in question.  Tags and parallel set membership
01684  *  are migrated as well as the appropriate adjacency info.
01685  *  An iMeshP request handle is returned.
01686  *
01687  *  COMMUNICATION:  point-to-point, non-blocking, pull.
01688  *
01689  *  \param  instance          (In)  Mesh instance containing the partition.
01690  *  \param  partition         (In)  The partition being queried.
01691  *  \param  part              (In)  The part to which the entity is migrated.
01692  *  \param  local_entity      (In)  The local entity copy for the entity to be
01693  *                                  migrated.
01694  *  \param  request           (Out) The iMeshP request handle returned.
01695  *  \param  err               (Out) Error code.
01696  */
01697 void iMeshP_migrateEntity( iMesh_Instance instance,
01698                            const iMeshP_PartitionHandle partition,
01699                            iMeshP_PartHandle part,
01700                            iBase_EntityHandle local_entity,
01701                            iMeshP_RequestHandle* request,
01702                            int* err );
01703 
01704 /** \brief Update vertex coordinates for vertex copies.
01705  *
01706  *  For a given vertex, update its copies with the vertex's coordinates.
01707  *  This function assumes that a local vertex's coordinates were updated
01708  *  through a call to iMesh_setVtxCoords.  This function then updates all
01709  *  copies of the vertex with the updated coordinates.
01710  *  The communication here is push-and-forget; as such,
01711  *  no request handle needs to be returned.
01712  *
01713  *  COMMUNICATION:  point-to-point, non-blocking, push-and-forget.
01714  *
01715  *  \param  instance          (In)  Mesh instance containing the partition.
01716  *  \param  partition         (In)  The partition being queried.
01717  *  \param  local_vertex      (In)  The vertex whose copies should be updated.
01718  *  \param  err               (Out) Error code.
01719  */
01720 void iMeshP_updateVtxCoords( iMesh_Instance instance,
01721                              const iMeshP_PartitionHandle partition,
01722                              const iBase_EntityHandle local_vertex,
01723                              int* err );
01724 
01725 /** \brief Replace entities on the part boundary.
01726  *
01727  *  This function performs changes on the part boundary where the
01728  *  calling application can ensure that things are done
01729  *  identically on both sides and that the arguments are passed in an order
01730  *  that can be matched.  (Specifically, matching new entities should appear in
01731  *  the same order in the call array.)  An example is creation of new
01732  *  boundary edges during edge splitting.
01733  *  Communication here could be a
01734  *  two-way push-and-forget, or some variant on push-and-confirm.
01735  *  CHANGES: At Onkar's suggestion, added an offset array (similar to array
01736  *  adjacency requests) so that a single call can easily handle coordination
01737  *  with multiple entities on part-boundary.
01738  *
01739  *  COMMUNICATION:  point-to-point, non-blocking, push-and-forget.
01740  *
01741  *  \param  instance          (In)  Mesh instance containing the partition.
01742  *  \param  partition         (In)  The partition being queried.
01743  *  \param  old_entities      (In)  The entities to be replaced.
01744  *  \param  old_entities_size (In)  The number of entities to be replaced.
01745  *  \param  new_entities      (In)  The entities that replace the old entities.
01746  *  \param  new_entities_size (In)  The number of entities in new_entities.
01747  *  \param  offset            (In)  Index into new_entities; old_entities[i]
01748  *                                  is replaced by new_entities[offset[i]] to
01749  *                                  new_entities[offset[i+1]-1].
01750  *  \param  offset_size       (In)  The number of entries in offset.
01751  *  \param  err               (Out) Error code.
01752  */
01753 void iMeshP_replaceOnPartBdry( iMesh_Instance instance,
01754                                const iMeshP_PartitionHandle partition,
01755                                const iBase_EntityHandle* old_entities,
01756                                const int old_entities_size,
01757                                const iBase_EntityHandle* new_entities,
01758                                const int new_entities_size,
01759                                const int* offset,
01760                                const int offset_size,
01761                                int* err );
01762 
01763 /** \brief Push ghost copies of individual entities onto other parts.
01764  *
01765  *  Given an entity and a target part, create a ghost copy of the entity on
01766  *  the target part.
01767  *
01768  *  Communication here is push-and-confirm (so that the original knows remote
01769  *  entity handle of the created ghosts).  The closure of a new ghost is pushed
01770  *  automatically as part of the underlying communication.
01771  *
01772  *  COMMUNICATION:  point-to-point, non-blocking, push.
01773  *
01774  *  \param  instance          (In)  Mesh instance containing the partition.
01775  *  \param  partition         (In)  The partition being queried.
01776  *  \param  target_part_id    (In)  The part to receive the new ghost.
01777  *  \param  entity_to_copy    (In)  The entity to be copied in target_part_id.
01778  *  \param  request           (Out) The iMeshP request handle returned.
01779  *  \param  err               (Out) Error code.
01780  */
01781 void iMeshP_addGhostOf( iMesh_Instance instance,
01782                         const iMeshP_PartitionHandle partition,
01783                         const iMeshP_Part target_part_id,
01784                         iBase_EntityHandle entity_to_copy,
01785                         iMeshP_RequestHandle* request,
01786                         int* err );
01787 
01788 /** \brief Remove ghost copies of individual entities from other parts.
01789  *
01790  *  Given an entity and a target part, remove the ghost copy of the entity on
01791  *  the target part.
01792  *
01793  *  Communication is push-and-forget; as such, no request handle is needed.
01794  *  The remote part will clean up the closure of the removed ghost
01795  *  as appropriate during deletion.
01796  *
01797  *  COMMUNICATION:  point-to-point, non-blocking, push-and-forget.
01798  *
01799  *  \param  instance          (In)  Mesh instance containing the partition.
01800  *  \param  partition         (In)  The partition being queried.
01801  *  \param  target_part_id    (In)  The part to lose the ghost.
01802  *  \param  copy_to_purge     (In)  The entity whose ghost is removed from
01803  *                                  target_part_id.
01804  *  \param  err               (Out) Error code.
01805  */
01806 void iMeshP_rmvGhostOf( iMesh_Instance instance,
01807                         const iMeshP_PartitionHandle partition,
01808                         const iMeshP_Part target_part_id,
01809                         iBase_EntityHandle copy_to_purge,
01810                         int* err );
01811 
01812 /** \brief Indicate completion of mesh modification.
01813  *
01814  *  Calling this function indicates that the user is finished with mesh
01815  *  modification for now.  With mesh modification complete, the implementation
01816  *  can update ghost, partition, boundary, and other information to
01817  *  re-establish a valid distributed mesh.  This function waits for all
01818  *  message traffic to clear and rebuilds ghost information that was
01819  *  allowed to go obsolete during mesh modification.
01820  *
01821  *  COMMUNICATION:  collective.
01822  *
01823  *  \param  instance          (In)  Mesh instance containing the partition.
01824  *  \param  partition         (In)  The partition being queried.
01825  *  \param  err               (Out) Error code.
01826  */
01827 void iMeshP_syncMeshAll( iMesh_Instance instance, iMeshP_PartitionHandle partition, int* err );
01828 
01829 /*--------------------------------------------------------------------------*/
01830 /*         Functions to send Tag data from owning entities to copies.       */
01831 /*--------------------------------------------------------------------------*/
01832 
01833 /**\brief  Synchronously send tag data for given entity types and topologies.
01834  *
01835  *  Send tag information for shared entities of specified type and
01836  *  topology.  The tag data is "pushed" from the owner entities to all copies.
01837  *  This version operates on all shared entities of specified type and topology
01838  *  (or all types/topologies if iBase_ALL_TYPES/iMesh_ALL_TOPOLOGIES are
01839  *  given).  This function assumes tag handles given on various
01840  *  calling parts are consistent; i.e. they have the same name,
01841  *  data type, size, etc.  This call blocks until communication is
01842  *  completed.
01843  *
01844  *  COMMUNICATION:  point-to-point, blocking.
01845  *
01846  *  \param  instance          (In)  Mesh instance containing the partition.
01847  *  \param  partition         (In)  The partition being queried.
01848  *  \param  source_tag        (In)  Tag handle for the sending entities.
01849  *  \param  dest_tag          (In)  Tag handle for the receiving entities.
01850  *  \param  entity_type       (In)  Tag data is exchanged only for this
01851  *                                  entity type.
01852  *  \param  entity_topo       (In)  Tag data is exchanged only for this
01853  *                                  entity topology.
01854  *  \param  err               (Out) Error code.
01855  */
01856 void iMeshP_pushTags( iMesh_Instance instance,
01857                       const iMeshP_PartitionHandle partition,
01858                       iBase_TagHandle source_tag,
01859                       iBase_TagHandle dest_tag,
01860                       int entity_type,
01861                       int entity_topo,
01862                       int* err );
01863 
01864 /**\brief  Synchronously send tag data for individual entities.
01865  *
01866  *  Send tag information for the specified entities.
01867  *  The tag data is "pushed" from the owner entities to all copies.
01868  *  This function assumes tag handles given on various
01869  *  calling parts are consistent; i.e. they have the same name,
01870  *  data type, size, etc.  This call blocks until communication is
01871  *  completed.
01872  *
01873  *  COMMUNICATION:  point-to-point, blocking.
01874  *
01875  *  \param  instance        (In)  Mesh instance containing the partition.
01876  *  \param  partition       (In)  The partition being queried.
01877  *  \param  source_tag      (In)  Tag handle for the sending entities.
01878  *  \param  dest_tag        (In)  Tag handle for the receiving entities.
01879  *  \param  entities        (In)  Owned entities for which to send data.
01880  *  \param  entities_size   (In)  The number of entities for which to send data.
01881  *  \param  err             (Out) Error code.
01882  */
01883 void iMeshP_pushTagsEnt( iMesh_Instance instance,
01884                          const iMeshP_PartitionHandle partition,
01885                          iBase_TagHandle source_tag,
01886                          iBase_TagHandle dest_tag,
01887                          const iBase_EntityHandle* entities,
01888                          int entities_size,
01889                          int* err );
01890 
01891 /**\brief  Asynchronously send tag data for given entity types and topologies.
01892  *
01893  *  Send tag information for shared entities of specified type and
01894  *  topology.  The tag data is "pushed" from the owner entities to all copies.
01895  *  This version operates on all shared entities of specified type and topology
01896  *  (or all types/topologies if iBase_ALL_TYPES/iMesh_ALL_TOPOLOGIES are
01897  *  given).  This function assumes tag handles given on various
01898  *  calling parts are consistent; i.e. they have the same name,
01899  *  data type, size, etc.
01900  *  This call does not block; applications should call
01901  *  iMeshP_waitForRequest (or a similar wait function)
01902  *  to block until this push is completed.
01903  *
01904  *  COMMUNICATION:  point-to-point, non-blocking.
01905  *
01906  *  \param  instance          (In)  Mesh instance containing the partition.
01907  *  \param  partition         (In)  The partition being queried.
01908  *  \param  source_tag        (In)  Tag handle for the sending entities.
01909  *  \param  dest_tag          (In)  Tag handle for the receiving entities.
01910  *  \param  entity_type       (In)  Tag data is exchanged only for this
01911  *                                  entity type.
01912  *  \param  entity_topo       (In)  Tag data is exchanged only for this
01913  *                                  entity topology.
01914  *  \param  request           (Out) The iMeshP request handle returned.
01915  *  \param  err               (Out) Error code.
01916  */
01917 void iMeshP_iPushTags( iMesh_Instance instance,
01918                        const iMeshP_PartitionHandle partition,
01919                        iBase_TagHandle source_tag,
01920                        iBase_TagHandle dest_tag,
01921                        int entity_type,
01922                        int entity_topo,
01923                        iMeshP_RequestHandle* request,
01924                        int* err );
01925 
01926 /**\brief  Asynchronously send tag data for individual entities.
01927  *
01928  *  Send tag information for the specified entities.
01929  *  The tag data is "pushed" from the owner entities to all copies.
01930  *  This function assumes tag handles given on various
01931  *  calling parts are consistent; i.e. they have the same name,
01932  *  data type, size, etc.
01933  *  This call does not block; applications should call
01934  *  iMeshP_waitForRequest (or a similar wait function)
01935  *  to block until this push is completed.
01936  *
01937  *  COMMUNICATION:  point-to-point, non-blocking.
01938  *
01939  *  \param  instance        (In)  Mesh instance containing the partition.
01940  *  \param  partition       (In)  The partition being queried.
01941  *  \param  source_tag      (In)  Tag handle for the sending entities.
01942  *  \param  dest_tag        (In)  Tag handle for the receiving entities.
01943  *  \param  entities        (In)  Owned entities for which to send data.
01944  *  \param  entities_size   (In)  The number of entities for which to send data.
01945  *  \param  request         (Out) The iMeshP request handle returned.
01946  *  \param  err             (Out) Error code.
01947  */
01948 void iMeshP_iPushTagsEnt( iMesh_Instance instance,
01949                           const iMeshP_PartitionHandle partition,
01950                           iBase_TagHandle source_tag,
01951                           iBase_TagHandle dest_tag,
01952                           const iBase_EntityHandle* entities,
01953                           int entities_size,
01954                           iMeshP_RequestHandle* request,
01955                           int* err );
01956 
01957 /*------------------------------------------------------------*
01958  *                   GHOSTING                                 *
01959  *------------------------------------------------------------*/
01960 
01961 /* \brief Create ghost entities between parts.
01962  *
01963  *  Ghost entities are specified similar to 2nd-order adjacencies, i.e.,
01964  *  through a "bridge" dimension.  The number of layers is measured from
01965  *  the inter-part interfaces.  For example, to get two layers of region
01966  *  entities in the ghost layer, measured from faces on the interface,
01967  *  use ghost_dim=3, bridge_dim=2, and num_layers=2.
01968  *  The number of layers specified is with respect to the global mesh;
01969  *  that is, ghosting may extend beyond a single neighboring processor if the
01970  *  number of layers is high.
01971  *
01972  *  Ghost information is cached in the partition.
01973  *  The triplet describing a ghosting "rule" (ghost dim, bridge dim, #
01974  *  layers) is stored in the partition; ghosting that became incorrect
01975  *  due to mesh modification or redistribution of mesh entities is
01976  *  re-established using these rules by the end
01977  *  of iMeshP_syncPartitionAll and iMeshP_syncMeshAll.
01978  *  Implementations can choose to keep ghosting consistent throughout
01979  *  mesh modification, but ghosts are not required to be consistent until
01980  *  the end of these two functions.
01981 
01982  *  iMeshP_createGhostEntsAll is cumulative; that is, multiple calls can only
01983  *  add more ghosts, not eliminate previous ghosts.
01984  *
01985  *  COMMUNICATION:  Collective.  Blocking.
01986  *
01987  *  \param  instance          (In)  Mesh instance containing the partition.
01988  *  \param  partition         (In)  The partition in which to create ghosts.
01989  *  \param  ghost_type        (In)  Entity type of entities to be ghosted.
01990  *  \param  bridge_type       (In)  Entity type through which bridge
01991  *                                  adjacencies are found.
01992  *  \param  num_layers        (In)  Number of layers of ghost entities.
01993  *  \param  include_copies    (In)  Flag indicating whether to create ghosts
01994  *                                  of non-owned part boundary entities
01995  *                                  (YES=1, NO=0).
01996  *  \param  err               (Out) Error code.
01997  */
01998 void iMeshP_createGhostEntsAll( iMesh_Instance instance,
01999                                 iMeshP_PartitionHandle partition,
02000                                 int ghost_type,
02001                                 int bridge_type,
02002                                 int num_layers,
02003                                 int include_copies,
02004                                 int* err );
02005 
02006 /* \brief Delete all ghost entities between parts.
02007  *
02008  *  Given a partition, delete all ghost entities in that partition of the mesh.
02009  *
02010  *  COMMUNICATION:  Collective.  Blocking.
02011  *
02012  *  \param  instance          (In)  Mesh instance containing the partition.
02013  *  \param  partition         (In)  The partition from which to delete ghosts.
02014  *  \param  err               (Out) Error code.
02015  *
02016  */
02017 void iMeshP_deleteGhostEntsAll( iMesh_Instance instance, iMeshP_PartitionHandle partition, int* err );
02018 
02019 /** \brief Return information about all ghosting on a partition.
02020  *
02021  *  Return the ghosting rules established through calls to
02022  *  iMeshP_createGhostEntsAll.
02023  *
02024  *  COMMUNICATION:  None.
02025  *
02026  *  \param  instance               (In)     Mesh instance containing the
02027  *                                          partition.
02028  *  \param  partition              (In)     The partition to be queried.
02029  *  \param  ghost_rules_allocated  (In/Out) Allocated size of ghost_type,
02030  *                                          bridge_type and num_layers.
02031  *  \param  ghost_rules_size       (Out)    Occupied size of ghost_type,
02032  *                                          bridge_type and num_layers;
02033  *                                          equal to the number of ghosting
02034  *                                          rules currently registered in
02035  *                                          the partition.
02036  *  \param  ghost_type             (Out)    Entity type of ghost entities
02037  *                                          for each rule.
02038  *  \param  bridge_type            (Out)    Entity type of bridge entities
02039  *                                          for each rule.
02040  *  \param  num_layers             (Out)    Number of layers of ghosts in each
02041  *                                          rule.
02042  *  \param  err                    (Out)    Error code.
02043  */
02044 void iMeshP_ghostEntInfo( const iMesh_Instance instance,
02045                           const iMeshP_PartitionHandle partition,
02046                           int* ghost_rules_allocated,
02047                           int* ghost_rules_size,
02048                           int** ghost_type,
02049                           int** bridge_type,
02050                           int** num_layers,
02051                           int* err );
02052 
02053 /*--------------------------------------------------------------------------
02054             FILE I/O
02055  --------------------------------------------------------------------------*/
02056 /* iMeshP file I/O closely aligns with iMesh file I/O.  The major
02057  * change is the addition of a iMeshP_PartitionHandle argument to both
02058  * iMeshP_loadAll and iMeshP_saveAll, enabling I/O from parallel processes.
02059  * For now, individual implementations will support different sets of
02060  * options; Tim and Ken will work to unify the options by SC08.
02061  */
02062 
02063 /** \brief Populate a mesh instance and a partition by reading data from files.
02064  *
02065  *  Before calling iMeshP_loadAll, the application creates both a mesh
02066  *  instance and a partition handle.  iMeshP_loadAll then reads the
02067  *  specified file, inserts entities into the mesh instance, constructs
02068  *  parts within the partition, and inserts entities into the parts.
02069  *  Options allow n>=1 files on p processes.
02070  *  Optional capabilities of iMeshP_loadAll include computing an initial
02071  *  partition (e.g., if a serial mesh file without part assignments is read)
02072  *  and creating ghost entities as requested by the application; the
02073  *  availability of these options is implementation dependent.
02074  *
02075  *  COMMUNICATION:  Collective.
02076  *
02077  *  \param  instance            (In)  Mesh instance to contain the data.
02078  *  \param  partition           (In)  The newly populated partition.
02079  *  \param  entity_set          (In)  Set to which the mesh will be added.
02080  *  \param  name                (in)  File name from which mesh data is read.
02081  *  \param  options             (In)  Implementation-specific options string.
02082  *  \param  err                 (Out) Error code.
02083  *  \param  name_len            (In)  Length of the file name character string.
02084  *  \param  options_len         (In)  Length of the options character string.
02085  */
02086 void iMeshP_loadAll( iMesh_Instance instance,
02087                      const iMeshP_PartitionHandle partition,
02088                      const iBase_EntitySetHandle entity_set,
02089                      const char* name,
02090                      const char* options,
02091                      int* err,
02092                      int name_len,
02093                      int options_len );
02094 
02095 /** \brief Write data from a mesh instance and a partition to files.
02096  *
02097  *  iMeshP_saveAll writes mesh and partition data to the specified file.
02098  *  Options allow n>=1 files on p processes.
02099  *
02100  *  COMMUNICATION:  Collective.
02101  *
02102  *  \param  instance            (In)  Mesh instance containing the partition.
02103  *  \param  partition           (In)  The partition being saved.
02104  *  \param  entity_set          (In)  Set from which data will be saved.
02105  *  \param  name                (in)  File name to which mesh data is written.
02106  *  \param  options             (In)  Implementation-specific options string.
02107  *  \param  err                 (Out) Error code.
02108  *  \param  name_len            (In)  Length of the file name character string.
02109  *  \param  options_len         (In)  Length of the options character string.
02110  */
02111 void iMeshP_saveAll( iMesh_Instance instance,
02112                      const iMeshP_PartitionHandle partition,
02113                      const iBase_EntitySetHandle entity_set,
02114                      const char* name,
02115                      const char* options,
02116                      int* err,
02117                      const int name_len,
02118                      int options_len );
02119 
02120 /*
02121 ------------------------------------------------
02122 Major Items left to do:
02123 -  Support for multiple partitions.
02124    We discussed designating a given partition as
02125    the "active" partition; i.e., the partition that is actually used in
02126    the distribution of mesh data in distributed memory.  We were concerned
02127    that when multiple partitions were used, multiple copies of mesh
02128    entities would be needed to fully support multiple partitions at the
02129    same time.  Designating one partition as "active" would store data
02130    with respect to only one partition.
02131 -  File I/O support.
02132    Need common set of options to allow interoperability.
02133    Support single files, N << P files on P processes, and P files.
02134    Support reading and writing partition information.
02135    Support initial parallel partitioning of serial file data.
02136    Support storing mapping of parts to processes in files.
02137 
02138 ------------------------------------------------
02139 Minor Items left to do:
02140 -  Determine which capabilities need both "getNumX" and "getX" functions.
02141    That is, when would an application need "getNumX" to allocate memory
02142    for "getX" or separately from "getX".  When could we use only "getX"
02143    and return numX as a byproduct.
02144 
02145 -  Determine with functions need "Ent" and "EntArr" versions, or whether
02146    we should adopt only the more general "EntArr" version.
02147 
02148 -  Determine whether to revise iMeshP_createPartition to make it less MPI
02149    specific.  We don't want to require applications to link with MPI if the
02150    implementation doesn't require it.  We may define an ITAPS_Comm name
02151    typedef'ed appropriately.
02152 
02153 -  iMeshP_getOwnerCopy could be achieved by calling iMeshP_getOwnerPart
02154    followed by iMeshP_getCopyOnPart.  Do we want to keep iMeshP_getOwnerCopy?
02155 
02156 -  Need function to receive tag data from part-boundary entities in owner.
02157    Possible options:  return the tag data values received directly, or
02158    include a mathematical operation (similar to MPI_SUM). 9/15/08
02159 
02160 ------------------------------------------------
02161 Comments and resolved questions:
02162 
02163 - Applications will build partitions by (1) creating a partition handle
02164   on each process to be included in the partition; (2) adding parts to
02165   the partition handle within the process; (3) populating the parts with
02166   entities, and (4) calling iMeshP_syncPartitionAll to allow the
02167   implementation to compute global data for the partition.
02168 
02169 - For now, we will not include an iterator over local (to a
02170   process) parts within a partition.  If it is needed, it can be added
02171   later.
02172 
02173 - We will not provide capability to move entire parts to new
02174   processes;  instead, the new process must create the part in its
02175   partition handle and then receive (perhaps in bulk) the entities to
02176   populate the part.  In other words, parts can be added to only a local
02177   partition handle.
02178 
02179 - Currently, iMesh doesn't have the functionality to get entities or
02180   entity sets by type and tag in serial.  Should it?
02181   Many people said it would be useful; others said it could be costly
02182   (in parallel) or numerically difficult (for floating point values).
02183   This issue is an iMesh issue, not a parallel interface issue, so
02184   for this document, the issue is resolved.  The resolution:  If
02185   iMesh adopts this capability, we will add it to the
02186   parallel interface.
02187 
02188 - We will not include functions that return all entities with
02189   given characteristics within a partition; the memory use of these
02190   functions can be large.  Instead, we will return entity information
02191   with respect to parts and/or mesh instances.  If the user wants such
02192   info, he should go through the mechanics of gathering it himself so
02193   that he is painfully aware of how much memory he is allocating.
02194   Removed the following global queries:
02195   + All tag names over the partition;
02196   + All entities in this partition having a given type, tag and/or
02197     tag name.
02198   + All entity sets in this partition having a given
02199     type, tag and/or tag name.
02200 
02201 - We will not include functions that return information about each
02202   part and/or process in a partition.  Such functions limit memory
02203   scalability for large numbers of parts.  If the user wants such
02204   info, he should go through the mechanics of gathering it himself so
02205   that he is painfully aware of how much memory he is allocating.
02206   Removed the following global queries:
02207   + The number of entities in each part of the partition;
02208   + The number of entity sets in each part of the partition;
02209   + The number of entities with given type, tag, and/or
02210     tag name in each part of the partition;
02211   + The number of entity sets with given type, tag,
02212     and/or tag name in each part of the partition;
02213   + All tag names in each part of the partition;
02214 
02215 - For functions that replace a set handle with a part handle, return
02216   all appropriate entities in a part, whether they are owned or are
02217   copies.  The application can test for ownership if needed.
02218 
02219 - Part assignments computed with respect to a set of
02220   entities induce part assignments to adjacent entities in an
02221   implementation-dependent fashion.  That is, if a partition is computed
02222   with respect to regions, queries about ownership of faces and vertices
02223   are valid.
02224 
02225 ------------------------------------------------
02226 Discussed but unresolved questions:
02227 
02228 - We discussed adding functions that give
02229   hints to an implementation about which data mappings the application
02230   will use, allowing the implementation to pre-compute them if it chooses
02231   to.  The example discussed was mapping between entities and parts, but
02232   other examples in iMesh may also exist.
02233 
02234 - We discussed adding an iterator over entities
02235   with given type/topology in a set or part.  We have non-iterator
02236   functionality, but not an iterator.
02237   KDD:  Is this true?  What is iMesh_initEntIter (and its analogous
02238   KDD:  iMeshP_initEntIter)?
02239 
02240 - We discussed storing in a partition
02241   information about which "objects" were used in computing the partition.
02242   These objects can be single entities or groups of entities.
02243   KDD:  Perhaps this capability should be part of the load-balancing service.
02244 
02245 - We discussed designating a given partition as
02246   the "active" partition; i.e., the partition that is actually used in
02247   the distribution of mesh data in distributed memory.  We were concerned
02248   that when multiple partitions were used, multiple copies of mesh
02249   entities would be needed to fully support multiple partitions at the
02250   same time.  Designating one partition as "active" would store data
02251   with respect to only one partition.
02252 
02253 ------------------------------------------------
02254 Not-yet-discussed, unresolved questions
02255 
02256 Entity questions:
02257 - From Carl:  "getTag*Operate: Again, we haven't got this in serial.  Does
02258   the existence of such operations imply that we expect to implement
02259   fields as tags? (Because that wasn't what I was assuming about field
02260   implementations at all, personally...)  Note that I'm not opposed to
02261   this sort of global reduction operation, I just wonder whether it'll see
02262   use outside of field-like situations.  If not, then it should be in
02263   parallel fields, not parallel mesh, and usage for
02264   fields-implemented-as-tags should be handled there."
02265 */
02266 
02267 /*--------------------------------*/
02268 /* NOTES FROM BOOTCAMP MARCH 2008 */
02269 /*--------------------------------*/
02270 /*
02271 -  Changed getPartRank to getRankOfPart.  (Carl)
02272 -  Made sure iMeshP_getNumOfTypeAll and iMeshP_getNumOfTopoAll were
02273 documented as collective operations.  (Carl)
02274 -  Changed suffix "Par" to "All".  (Lori)
02275 -  Added iMeshP_testPart() to test status of part handle, returning
02276 LOCAL, REMOTE, or INVALID.  (Mark M, Lori).
02277 6/25/08:  Removed this function since part handles can no longer be remote.
02278 If an application wants to test the validity of a part handle, it can try
02279 to compute its Part ID.
02280 -  Changed iMeshP_addCopyOf and iMeshP_rmvCopyOf back to
02281 iMeshP_addGhostOf and iMeshP_rmvGhostOf.  If we wanted to use these
02282 functions for adding boundary copies, we'd have to include a list of
02283 already existing remote copies in the arguments, as well as
02284 communicate with parts already owning copies to let them know a ghost
02285 copy has been made.  Actually, this raises an interesting question:
02286 does a boundary copy need to know about all ghost copies of it?
02287 -  Change getEntParStatus to getEntStatus.  (Lori)
02288 -  Changed sendEntArrToPartsPar to exchEntArrToPartsAll.  (Lori,Tim)
02289 
02290 
02291 Parts and Processes:
02292 -  Martin argued for consecutive unique Part IDs in addition to or
02293 instead of Part handles.  He will send use cases.   If we decide to
02294 add them back to the interface, we could compute them in
02295 iMeshP_syncPartitionAll rather than in iMeshP_createPart.  That is, an
02296 application couldn't access them until after iMeshP_syncPartitionAll.
02297 6/25/08:  On follow-up, Martin couldn't recall why having consecutive
02298 PartIDs was necessary.  While we all agree they are conceptually nice,
02299 they are difficult to implement and not really necessary.  Part IDs will
02300 be globally unique but not necessarily consecutive.
02301 -  Are part handles globally unique?  They probably need to be
02302 globally unique in order for them to be useful as remote part
02303 handles.  Also, does the process rank need to be encoded in the part
02304 handle in order to map from parts to processes for communication?
02305 6/25/08:  DECIDED:  We will have globally unique part IDs.  Part handles
02306 will be valid for only local parts.  Accessing remote parts must be done
02307 via Part IDs.
02308 -  If in iMeshP_syncPartitionAll, we computed a mapping from part
02309 handles to integers 0,..., k-1, we could store only ranges of
02310 integers to achieve the part-to-process and process-to-parts mappings;
02311 this would require O(P) storage per process for P processes.
02312 6/5/08:  DECIDED:  Do not need getPartOnRank or getNumPartOnRank.  These
02313 functions were troublesome due to their storage or communication requirements.
02314 We decided to remove them.
02315 -  Alternatively, the mapping of all parts to processes can be stored
02316 in O(k) total memory, distributed across processors (e.g., a
02317 distributed data directory) but interrogating the directory requires
02318 communication.
02319 6/5/08:  See note above.
02320 -  iMeshP_getPartsOnRank created discussion and needs to be resolved.
02321 IMeshP_getPartsOnRank would likely require either O(k) storage per
02322 process for k parts or communication.  For other points, please see
02323 Mark M's 3/12/08 email.
02324 6/5/08:  See note above.
02325 
02326 CreateEnt:
02327 -  Carl asked if we should have a version of createEnt that accepts a
02328 part handle.  Should this function be used only for creating owned
02329 entities?   How do you envision creating part boundary entities when a
02330 parallel mesh is initially loaded?
02331 
02332 Ghost entities:
02333 -  We currently have a mechanism only for pushing ghosts onto other
02334 parts.  Will we want a mechanism for pulling them, too?  (E.g., a
02335 part says, "I want ghosts for this entity.")
02336 
02337 PartNbor functions:
02338 -  Did we agree to remove the entity type from these functions?  That
02339 is, do we want to return the part IDs for all parts that have
02340 any copies?  The entity type was intended to allow us to get the part
02341 IDs for all parts that have copies of a given type (perhaps
02342 ALL_TYPES).
02343 
02344 Functions handling both Parts and Entity Sets:
02345 -  Tim said these function names (e.g., iMeshP_getNumOfType,
02346 iMeshP_getAllVtxCoord) are too close to existing iMesh function
02347 names, even though the argument lists would be different.  He agreed
02348 to email suggestions for better names.
02349 
02350 Copies:
02351 -  Functions getNumCopies, getCopies, getCopyParts, and getCopyOnPart
02352 have different behavior for ghost and part-boundary copies.  Ghosts
02353 will return only itself and its owner in getCopies; part-boundary
02354 entities will return copies on other parts as well.
02355 -  Tim envisions applications (e.g., FETI methods) updating tag data
02356 in their copies that they would like to accumulate back to the
02357 owner.  Xiaolin said that he writes in his ghosts, but doesn't send
02358 those values back to the owner.  Currently, we have the ability
02359 to send tag data only from owners to ghosts.  Tim will look at this issue
02360 and propose a solution.
02361 
02362 Communication:
02363 -  Although we should think in terms of parts, communication really
02364 occurs with respect to processes.  We need to make sure all our
02365 communication routines make sense with respect to both processes and
02366 parts, and perhaps, revise their descriptions.  Also, if we send to
02367 parts, the implementation really does need the mapping of parts to
02368 processes.
02369 
02370 Entity Owner/Status Queries:
02371 -  Should we combine functions getEntOwnerPart and getEntStatus into
02372 one function?  Or should we combine functions getOwnerCopy and
02373 getEntOwner into one function?  Or should we remove getOwnerCopy and
02374 make applications call getOwnerPart followed by getCopyOnPart?
02375 
02376 Reducing storage:
02377 -  Mark Miller proposed allowing the user to specify the amount of
02378 copying done by the implementation, depending on applications' needs.
02379 For example, for a static viz application, every boundary entity may not
02380 need to know where all its copies are, so the implementation would not
02381 have to store them.  Can the implementations accept a flag advising them how
02382 much copying is needed?  If so, the implementations could choose to
02383 optimize storage or ignore the flag.
02384 */
02385 
02386 /*--------------------------------------------------------------------
02387  * SVN File Information
02388  *
02389  *   $SVN:Author$
02390  *   $SVN:Date$
02391  *   $SVN:Revision$
02392  *--------------------------------------------------------------------
02393  */
02394 
02395 #ifdef __cplusplus
02396 } /*  extern "C"  */
02397 #endif
02398 
02399 #endif /* !defined(_ITAPS_iMeshP) */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines