MOAB: Mesh Oriented datABase  (version 5.2.1)
Interface.hpp
Go to the documentation of this file.
00001 /** \mainpage The Mesh-Oriented datABase (MOAB)
00002  *
00003  * MOAB is a component for representing and evaluating mesh data.  MOAB can store
00004  * structured and unstructured mesh, consisting of elements in the finite element “zoo”,
00005  * along with polygons and polyhedra.  The functional interface to MOAB is simple, consisting
00006  * of only four fundamental data types.  This data is quite powerful, allowing the representation
00007  * of most types of metadata commonly found on the mesh.  MOAB is optimized for efficiency in
00008  * space and time, based on access to mesh in chunks rather than through individual entities,
00009  * while also versatile enough to support individual entity access.
00010  *
00011  * The MOAB data model consists of the following four fundamental types: mesh interface instance,
00012  * mesh entities (vertex, edge, tri, etc.), sets, and tags.  Entities are addressed through handles
00013  * rather than pointers, to allow the underlying representation of an entity to change without
00014  * changing the handle to that entity.  Sets are arbitrary groupings of mesh entities and other
00015  * sets.  Sets also support parent/child relationships as a relation distinct from sets containing
00016  * other sets.  The directed-graph provided by set parent/child relationships is useful for modeling
00017  * topological relations from a geometric model and other metadata.  Tags are named data which can
00018  * be assigned to the mesh as a whole, individual entities, or sets.  Tags are a mechanism for
00019  * attaching data to individual entities and sets are a mechanism for describing relations between
00020  * entities; the combination of these two mechanisms is a powerful yet simple interface for
00021  * representing metadata or application-specific data.  For example, sets and tags can be used
00022  * together to describe geometric topology, boundary condition, and inter-processor interface
00023  * groupings in a mesh.
00024  *
00025  * MOAB's API is documented in the moab::Interface class.  Questions and comments should be sent to
00026  * moab-dev _at_ mcs.anl.gov.
00027  *
00028  * \ref userguide "User's Guide"
00029  *
00030  * \ref developerguide "Developer's Guide"
00031  *
00032  * \ref metadata "I/O and Meta-Data Storage Conventions in MOAB"
00033  *
00034  * <a href="pages.html">Full List of Documents</a>
00035  */
00036 
00037 #ifdef WIN32               /* windows */
00038 #define _USE_MATH_DEFINES  // For M_PI
00039 #endif
00040 #ifndef MOAB_INTERFACE_HPP
00041 #define MOAB_INTERFACE_HPP
00042 
00043 #define MOAB_API_VERSION        1.01
00044 #define MOAB_API_VERSION_STRING "1.01"
00045 
00046 #include "moab/MOABConfig.h"
00047 #include "moab/Forward.hpp"
00048 #include "moab/Range.hpp"
00049 #include "moab/Compiler.hpp"
00050 #include "moab/ErrorHandler.hpp"
00051 
00052 // include files
00053 #include <string>
00054 #include <functional>
00055 #include <typeinfo>
00056 
00057 //! component architecture definitions
00058 #ifdef XPCOM_MB
00059 
00060 #ifndef __gen_nsISupports_h__
00061 #include "nsISupports.h"
00062 #endif
00063 
00064 #ifndef NS_NO_VTABLE
00065 #define NS_NO_VTABLE
00066 #endif
00067 
00068 #define MBINTERFACE_IID_STR "f728830e-1dd1-11b2-9598-fb9f414f2465"
00069 
00070 #define MBINTERFACE_IID                                    \
00071     {                                                      \
00072         0xf728830e, 0x1dd1, 0x11b2,                        \
00073         {                                                  \
00074             0x95, 0x98, 0xfb, 0x9f, 0x41, 0x4f, 0x24, 0x65 \
00075         }                                                  \
00076     }
00077 
00078 #endif
00079 
00080 #include "moab/UnknownInterface.hpp"
00081 #define MB_INTERFACE_VERSION "2.0.0"
00082 namespace moab
00083 {
00084 
00085 static const MBuuid IDD_MBCore = MBuuid( 0x8956e0a, 0xc300, 0x4005, 0xbd, 0xf6, 0xc3, 0x4e, 0xf7, 0x1f, 0x5a, 0x52 );
00086 
00087 /**
00088  * \class Interface Interface.hpp "moab/Interface.hpp"
00089  * \brief Main interface class to MOAB
00090  * \nosubgrouping
00091  */
00092 #if defined( XPCOM_MB )
00093 class NS_NO_VTABLE Interface : public nsISupports
00094 {
00095 #else
00096 class Interface : public UnknownInterface
00097 {
00098 #endif
00099 
00100   public:
00101 #ifdef XPCOM_MB
00102     NS_DEFINE_STATIC_IID_ACCESSOR( MBINTERFACE_IID )
00103 #endif
00104 
00105     /** \name Interface */
00106 
00107     /**@{*/
00108 
00109     //! constructor
00110     Interface() {}
00111 
00112     //! destructor
00113     virtual ~Interface() {}
00114 
00115     //! return the entity set representing the whole mesh
00116     virtual EntityHandle get_root_set() = 0;
00117 
00118     //! Get a pointer to an internal MOAB interface
00119     //!\return NULL if not found, iterface pointer otherwise
00120     virtual ErrorCode query_interface_type( const std::type_info& iface_type, void*& iface ) = 0;
00121 
00122     //! Get a pointer to an internal MOAB interface
00123     //!\return NULL if not found, iterface pointer otherwise
00124     template < class IFace >
00125     ErrorCode query_interface( IFace*& ptr )
00126     {
00127         void* tmp_ptr;
00128         ErrorCode result = query_interface_type( typeid( IFace ), tmp_ptr );
00129         ptr              = reinterpret_cast< IFace* >( tmp_ptr );
00130         return result;
00131     }
00132 
00133     //! Release reference to MB interface
00134     virtual ErrorCode release_interface_type( const std::type_info& iface_type, void* iface ) = 0;
00135 
00136     template < class IFace >
00137     ErrorCode release_interface( IFace* interface )
00138     {
00139         return release_interface_type( typeid( IFace ), interface );
00140     }
00141 
00142     //! Release reference to MB interface
00143 
00144     //! Returns the major.minor version number of the interface
00145     /**
00146        \param version_string If non-NULL, will be filled in with a string, possibly
00147        containing implementation-specific information
00148     */
00149     virtual float api_version( std::string* version_string = NULL );
00150 
00151     //! Returns the major.minor version number of the implementation
00152     /**
00153        \param version_string If non-NULL, will be filled in with a string, possibly
00154        containing implementation-specific information
00155     */
00156     virtual float impl_version( std::string* version_string = NULL ) = 0;
00157 
00158     /**@}*/
00159 
00160     /** \name Type and id */
00161 
00162     /**@{*/
00163 
00164     //! Returns the entity type of an EntityHandle.
00165     /** Returns the EntityType (ie, MBVERTEX, MBQUAD, MBHEX ) of <em>handle</em>.
00166         \param handle The EntityHandle you want to find the entity type of.
00167         \return type The entity type of <em>handle</em>.
00168 
00169         Example: \code
00170         EntityType type = type_from_handle( handle);
00171         if( type == MBHEX ) ...  \endcode
00172     */
00173     virtual EntityType type_from_handle( const EntityHandle handle ) const = 0;
00174 
00175     //! Returns the id from an EntityHandle.
00176     /** \param handle The EntityHandle you want to find the id of.
00177         \return id Id of <em>handle</em>
00178 
00179         Example: \code
00180         int id = id_from_handle(handle); \endcode
00181     */
00182     virtual EntityID id_from_handle( const EntityHandle handle ) const = 0;
00183 
00184     //! Returns the topological dimension of an entity
00185     /** Returns the topological dimension of an entity.
00186         \param handle The EntityHandle you want to find the dimension of.
00187         \return type The topological dimension of <em>handle</em>.
00188 
00189         Example: \code
00190         int dim = dimension_from_handle( handle);
00191         if( dim == 0 ) ...  \endcode
00192     */
00193     virtual int dimension_from_handle( const EntityHandle handle ) const = 0;
00194 
00195     //! Gets an entity handle from the data base, if it exists, according to type and id.
00196     /** Given an EntiyType and an id, this function gets the existent EntityHandle.
00197         If no such EntityHandle exits, it returns MB_ENTITY_NOT_FOUND
00198         and sets handle to zero.
00199         \param type The type of the EntityHandle to retrieve from the database.
00200         \param id The id of the EntityHandle to retrieve from the database.
00201         \param handle An EntityHandle of type <em>type</em> and <em>id</em>.
00202 
00203         Example: \code
00204         EntityType handle;
00205         ErrorCode error_code = handle_from_id(MBTRI, 204, handle );
00206         if( error_code == MB_ENTITY_NOT_FOUND ) ... \endcode
00207     */
00208     virtual ErrorCode handle_from_id( const EntityType type, const EntityID, EntityHandle& handle ) const = 0;
00209 
00210     /**@}*/
00211 
00212     /** \name Mesh input/output */
00213 
00214     /**@{*/
00215 
00216     //! Loads a mesh file into the database.
00217     /** Loads the file 'file_name'; types of mesh which can be loaded
00218         depend on modules available at MB compile time.  If
00219         active_block_id_list is NULL, all material sets (blocks in the
00220         ExodusII jargon) are loaded.  Individual material sets  can be
00221         loaded by specifying their ids in 'active_block_id_list'.  All
00222         nodes are loaded on first call for a given file.  Subsequent
00223         calls for a file load any material sets not loaded in previous
00224         calls.
00225         \param file_name Name of file to load into database.
00226         \param active_block_id_list Material set/block ids to load.
00227                 If NULL, ALL blocks of <em>file_name</em> are loaded.
00228         \param num_blocks Number of blocks in active_block_id_list
00229 
00230         Example: \code
00231         std::vector<int> active_block_id_list;
00232         int active_block_id_list[] = {1, 4, 10};
00233         load_mesh( "temp.gen", active_block_id_list, 3 );  //load blocks 1, 4, 10
00234         \endcode
00235     */
00236     virtual ErrorCode load_mesh( const char* file_name, const int* active_block_id_list = NULL,
00237                                  const int num_blocks = 0 ) = 0;
00238 
00239     /**\brief Load or import a file.
00240      *
00241      * Load a MOAB-native file or import data from some other supported
00242      * file format.
00243      *
00244      *\param file_name The location of the file to read.
00245      *\param file_set  If non-null, this argument must be a pointer to
00246      *                 a valid entity set handle.  All entities read from
00247      *                 the file will be added to this set.  File metadata
00248      *                 will be added to tags on the set.
00249      *\param options A list of string options, separated by semicolons (;).
00250      *               See README.IO for more information.  Options are typically
00251      *               format-specific options or parallel options.  If an
00252      *               option value is unrecognized but the file read otherwise
00253      *               succeeded, MB_UNHANDLED_OPTION will be returned.
00254      *\param set_tag_name The name of a tag used to designate the subset
00255      *               of the file to read.  The name must correspond to
00256      *               data in the file that will be instantiated in MOAB
00257      *               as a tag.
00258      *\param set_tag_values If the name specified in 'set_tag_name'
00259      *               corresponds to a tag with a single integer value,
00260      *               the values in this tag can be used to further
00261      *               limit the subset of data written from the file to
00262      *               only those entities or sets that have a value for
00263      *               the tag that is one of the values in this array.
00264      *\param num_set_tag_values The length of set_tag_values.
00265      *
00266      *\Note file_set is passed by pointer rather than by value (where a
00267      *      zero handle value would indicate no set) so as to intentionally
00268      *      break compatibility with the previous version of this function
00269      *      because the behavior with respect to the file set was changed.
00270      *      The file_set is now an input-only argument.  The previous
00271      *      version of this function unconditionally created a set and
00272      *      passed it back to the caller via a non-const reference argument.
00273      */
00274     virtual ErrorCode load_file( const char* file_name, const EntityHandle* file_set = 0, const char* options = 0,
00275                                  const char* set_tag_name = 0, const int* set_tag_values = 0,
00276                                  int num_set_tag_values = 0 ) = 0;
00277 
00278     //! Writes mesh to a file.
00279     /** Write mesh to file 'file_name'; if output_list is non-NULL, only
00280         material sets contained in that list will be written.
00281         \param file_name Name of file to write.
00282         \param output_list 1d array of material set handles to write; if
00283                            NULL, all sets are written
00284         \param num_sets Number of sets in output_list array
00285 
00286         Example: \code
00287         EntityHandle output_list[] = {meshset1, meshset2, meshset3};
00288         write_mesh( "output_file.gen", output_list, 3 ); \endcode
00289     */
00290     virtual ErrorCode write_mesh( const char* file_name, const EntityHandle* output_list = NULL,
00291                                   const int num_sets = 0 ) = 0;
00292 
00293     /**\brief Write or export a file.
00294      *
00295      * Write a MOAB-native file or export data to some other supported
00296      * file format.
00297      *
00298      *\param file_name The location of the file to write.
00299      *\param file_type The type of the file.  If this value is NULL,
00300      *                 then file type will be determined using the
00301      *                 file name suffix.
00302      *\param options   A semicolon-separated list of options.
00303      *                 See README.IO for more information.  Typical options
00304      *                 include the file type, parallel options, and options
00305      *                 specific to certain file formats.
00306      *\param output_sets A list of entity sets to write to the file.  If
00307      *                 no sets are sepcified, the default behavior is to
00308      *                 write all data that is supported by the target file
00309      *                 type.
00310      *\param num_output_sets The length of the output_sets array.
00311      *\param tag_list A list of tags for which to write the tag data.  The
00312      *                write may fail if a tag list is specified but the
00313      *                target file type is not capable of representing the
00314      *                data.  If no tags are specified, the default is to
00315      *                write whatever data the target file format supports.
00316      *\param num_tags The length of tag_list.
00317      */
00318     virtual ErrorCode write_file( const char* file_name, const char* file_type = 0, const char* options = 0,
00319                                   const EntityHandle* output_sets = 0, int num_output_sets = 0, const Tag* tag_list = 0,
00320                                   int num_tags = 0 ) = 0;
00321 
00322     /**\brief Write or export a file.
00323      *
00324      * Write a MOAB-native file or export data to some other supported
00325      * file format.
00326      *
00327      *\param file_name The location of the file to write.
00328      *\param file_type The type of the file.  If this value is NULL,
00329      *                 then file type will be determined using the
00330      *                 file name suffix.
00331      *\param options   A semicolon-separated list of options.
00332      *                 See README.IO for more information.  Typical options
00333      *                 include the file type, parallel options, and options
00334      *                 specific to certain file formats.
00335      *\param output_sets A list of entity sets to write to the file.  If
00336      *                 no sets are sepcified, the default behavior is to
00337      *                 write all data that is supported by the target file
00338      *                 type.
00339      *\param tag_list A list of tags for which to write the tag data.  The
00340      *                write may fail if a tag list is specified but the
00341      *                target file type is not capable of representing the
00342      *                data.  If no tags are specified, the default is to
00343      *                write whatever data the target file format supports.
00344      *\param num_tags The length of tag_list.
00345      */
00346     virtual ErrorCode write_file( const char* file_name, const char* file_type, const char* options,
00347                                   const Range& output_sets, const Tag* tag_list = 0, int num_tags = 0 ) = 0;
00348 
00349     //! Deletes all mesh entities from this MB instance
00350     virtual ErrorCode delete_mesh() = 0;
00351 
00352     /**@}*/
00353 
00354     /** \name Coordinates and dimensions */
00355 
00356     /**@{*/
00357 
00358     //! Get blocked vertex coordinates for all vertices
00359     /** Blocked = all x, then all y, etc.
00360 
00361     Example: \code
00362     std::vector<double> coords;
00363     get_vertex_coordinates(coords);
00364     double xavg = 0;
00365     for (int i = 0; i < coords.size()/3; i++) xavg += coords[i]; \endcode
00366     */
00367     virtual ErrorCode get_vertex_coordinates( std::vector< double >& coords ) const = 0;
00368 
00369     //! get pointers to coordinate data
00370     /** BEWARE, THIS GIVES ACCESS TO MOAB'S INTERNAL STORAGE, USE WITH CAUTION!
00371      * This function returns pointers to MOAB's internal storage for vertex coordinates.
00372      * Access is similar to tag_iterate, see documentation for that function for details
00373      * about arguments and a coding example.
00374      */
00375     virtual ErrorCode coords_iterate( Range::const_iterator iter,
00376                                       /**< Iterator to first entity you want coordinates for */
00377                                       Range::const_iterator end,
00378                                       /**< Iterator to last entity you want coordinates for */
00379                                       double*& xcoords_ptr,
00380                                       /**< Pointer to x coordinate storage for these entities */
00381                                       double*& ycoords_ptr,
00382                                       /**< Pointer to y coordinate storage for these entities */
00383                                       double*& zcoords_ptr,
00384                                       /**< Pointer to z coordinate storage for these entities */
00385                                       int& count
00386                                       /**< Number of entities for which returned pointers are valid/contiguous */
00387                                       ) = 0;
00388 
00389     //! Gets xyz coordinate information for range of vertices
00390     /** Length of 'coords' should be at least 3*<em>entity_handles.size()</em> before making call.
00391         \param entity_handles Range of vertex handles (error if not of type MBVERTEX)
00392         \param coords Array used to return x, y, and z coordinates.
00393 
00394         Example: \code
00395         double coords[3];
00396         get_coords( vertex_handle, coords );
00397         std::cout<<"x = "<<coords[0]<<std::endl;
00398         std::cout<<"y = "<<coords[1]<<std::endl;
00399         std::cout<<"z = "<<coords[2]<<std::endl; \endcode
00400     */
00401     virtual ErrorCode get_coords( const Range& entity_handles, double* coords ) const = 0;
00402 
00403     //! Gets xyz coordinate information for vector of vertices
00404     /** Identical to range-based function, except entity handles are specified using a 1d vector
00405         and vector length.
00406     */
00407     virtual ErrorCode get_coords( const EntityHandle* entity_handles, const int num_entities,
00408                                   double* coords ) const = 0;
00409 
00410     /**\brief Get vertex coordinates in blocks by dimension.
00411      *
00412      * Get the X, Y, and Z coordinates of a group of vertices.
00413      * Coordinates are returned in separate arrays, one for each
00414      * dimension.  Each coordinate array must be of sufficient
00415      * length to hold the coordinate value for each vertex.  Array
00416      * pointers may be NULL if coordinates in the the respective
00417      * dimension are not desired.
00418      *\param entity_handles  The group of vertex handles for which to get the coordiantes.
00419      *\param x_coords        Output: the X coordinate of each vertex.  May be NULL.
00420      *\param y_coords        Output: the Y coordinate of each vertex.  May be NULL.
00421      *\param z_coords        Output: the Z coordinate of each vertex.  May be NULL.
00422      */
00423     virtual ErrorCode get_coords( const Range& entity_handles, double* x_coords, double* y_coords,
00424                                   double* z_coords ) const = 0;
00425 
00426     //! Sets the xyz coordinates for a vector of vertices
00427     /** An error is returned if any entities in the vector are not vertices.
00428         \param entity_handles EntityHandle's to set coordinates of. (Must be of type MBVERTEX)
00429         \param num_entities Number of entities in entity_handles
00430         \param coords Array containing new xyz coordinates.
00431 
00432         Example: \code
00433         double coords[3] = {0.234, -2.52, 12.023};
00434         set_coords( entity_handle, 1, coords ); \endcode
00435     */
00436     virtual ErrorCode set_coords( const EntityHandle* entity_handles, const int num_entities,
00437                                   const double* coords ) = 0;
00438 
00439     //! Sets the xyz coordinates for a vector of vertices
00440     /** An error is returned if any entities in the vector are not vertices.
00441         \param entity_handles EntityHandle's to set coordinates of. (Must be of type MBVERTEX)
00442         \param num_entities Number of entities in entity_handles
00443         \param coords Array containing new xyz coordinates.
00444 
00445         Example: \code
00446         double coords[3] = {0.234, -2.52, 12.023};
00447         set_coords( entity_handle, 1, coords ); \endcode
00448     */
00449     virtual ErrorCode set_coords( Range entity_handles, const double* coords ) = 0;
00450 
00451     //! Get overall geometric dimension
00452     virtual ErrorCode get_dimension( int& dim ) const = 0;
00453 
00454     //! Set overall geometric dimension
00455     /** Returns error if setting to 3 dimensions, mesh has been created, and
00456      *  there are only 2 dimensions on that mesh
00457      */
00458     virtual ErrorCode set_dimension( const int dim ) = 0;
00459 
00460     /**@}*/
00461 
00462     /** \name Connectivity */
00463 
00464     /**@{*/
00465 
00466     //! get pointers to connectivity data
00467     /** BEWARE, THIS GIVES ACCESS TO MOAB'S INTERNAL STORAGE, USE WITH CAUTION!
00468      * This function returns a pointer to MOAB's internal storage for entity connectivity.
00469      * For each contiguous sub-range of entities, those entities are guaranteed to have
00470      * the same number of vertices (since they're in the same ElementSequence).  Count
00471      * is given in terms of entities, not elements of the connectivity array.
00472      * Access is similar to tag_iterate, see documentation for that function for details
00473      * about arguments and a coding example.
00474      */
00475     virtual ErrorCode connect_iterate( Range::const_iterator iter,
00476                                        /**< Iterator to first entity you want coordinates for */
00477                                        Range::const_iterator end,
00478                                        /**< Iterator to last entity you want coordinates for */
00479                                        EntityHandle*& connect,
00480                                        /**< Pointer to connectivity storage for these entities */
00481                                        int& verts_per_entity,
00482                                        /**< Number of vertices per entity in this block of entities */
00483                                        int& count
00484                                        /**< Number of entities for which returned pointers are valid/contiguous */
00485                                        ) = 0;
00486 
00487     //! Get the connectivity array for all entities of the specified entity type
00488     /**  This function returns the connectivity of just the corner vertices, no higher order nodes
00489          \param type The entity type of elements whose connectivity is to be returned
00490          \param connect an STL vector used to return connectivity array (in the form of entity
00491        handles)
00492     */
00493     virtual ErrorCode get_connectivity_by_type( const EntityType type, std::vector< EntityHandle >& connect ) const = 0;
00494 
00495     //! Gets the connectivity for a vector of elements
00496     /** Same as vector-based version except range is returned (unordered!)
00497      */
00498     virtual ErrorCode get_connectivity( const EntityHandle* entity_handles, const int num_handles, Range& connectivity,
00499                                         bool corners_only = false ) const = 0;
00500 
00501     //! Gets the connectivity for elements
00502     /** Same as vector-based version except range is returned (unordered!)
00503      */
00504     virtual ErrorCode get_connectivity( const Range& entity_handles, Range& connectivity,
00505                                         bool corners_only = false ) const = 0;
00506 
00507     //! Gets the connectivity for a vector of elements
00508     /** Corner vertices or all vertices (including higher-order nodes, if any) are returned.
00509         For non-element handles (ie, MB_MeshSets), returns an error. Connectivity data is copied
00510         from the database into the vector.  Connectivity of a vertex is the same vertex.
00511         The nodes in <em>connectivity</em> are properly ordered according to that element's
00512         canonical ordering.
00513         \param entity_handles Vector of element handles to get connectivity of.
00514         \param num_handles Number of entity handles in <em>entity_handles</em>
00515         \param connectivity Vector in which connectivity of <em>entity_handles</em> is returned.
00516         \param corners_only If true, returns only corner vertices, otherwise returns all of them
00517        (including any higher-order vertices) \param offsets If non-NULL, offsets->[i] stores the
00518        index of the start of entity i's connectivity, with the last value in offsets one beyond the
00519        last entry
00520     */
00521     virtual ErrorCode get_connectivity( const EntityHandle* entity_handles, const int num_handles,
00522                                         std::vector< EntityHandle >& connectivity, bool corners_only = false,
00523                                         std::vector< int >* offsets = NULL ) const = 0;
00524 
00525     //! Gets a pointer to constant connectivity data of <em>entity_handle</em>
00526     /** Sets <em>number_nodes</em> equal to the number of nodes of the <em>
00527         entity_handle </em>.  Faster then the other <em>get_connectivity</em> function because no
00528         data is copied.  The nodes in 'connectivity' are properly ordered according to the
00529         element's canonical ordering.
00530 
00531 
00532           Example: \code
00533           const EntityHandle* conn;
00534           int number_nodes = 0;
00535           get_connectivity( entity_handle, conn, number_nodes ); \endcode
00536 
00537           Example2: \code
00538           std::vector<EntityHandle> sm_storage;
00539           const EntityHandle* conn;
00540           int number_nodes;
00541           get_connectivity( handle, conn, number_nodes, false, &sm_storage );
00542           if (conn == &sm_storage[0])
00543             std::cout << "Structured mesh element" << std::endl;
00544           \endcode
00545 
00546         \param entity_handle EntityHandle to get connectivity of.
00547         \param connectivity Array in which connectivity of <em>entity_handle</em> is returned.
00548         \param num_nodes Number of MeshVertices in array <em>connectivity</em>.
00549         \param corners_only If true, returns only corner vertices, otherwise returns all of them
00550        (including any higher-order vertices) \param storage Some elements (e.g. structured mesh) may
00551        not have an explicit connectivity list.  This function will normally return
00552        MB_NOT_IMPLEMENTED for such elements.  However, if the caller passes in a non-null value for
00553        this argument, space will be allocated in this vector for the connectivity data and the
00554        connectivity pointer will be set to the data in this vector.
00555     */
00556     virtual ErrorCode get_connectivity( const EntityHandle entity_handle, const EntityHandle*& connectivity,
00557                                         int& num_nodes, bool corners_only = false,
00558                                         std::vector< EntityHandle >* storage = 0 ) const = 0;
00559 
00560     //! Sets the connectivity for an EntityHandle.  For non-element handles, return an error.
00561     /** Connectivity is stored exactly as it is ordered in vector <em>connectivity</em>.
00562         \param entity_handle EntityHandle to set connectivity of.
00563         \param connect Vector containing new connectivity of <em>entity_handle</em>.
00564         \param num_connect Number of vertices in <em>connect</em>
00565 
00566         Example: \code
00567         EntityHandle conn[] = {node1, node2, node3};
00568         set_connectivity( tri_element, conn, 3 ); \endcode
00569     */
00570     virtual ErrorCode set_connectivity( const EntityHandle entity_handle, EntityHandle* connect,
00571                                         const int num_connect ) = 0;
00572 
00573     /**@}*/
00574 
00575     /** \name Adjacencies */
00576 
00577     /**@{*/
00578 
00579     //! Get the adjacencies associated with a vector of entities to entities of a specfied
00580     //! dimension.
00581     /** \param from_entities Vector of EntityHandle to get adjacencies of.
00582         \param num_entities Number of entities in <em>from_entities</em>
00583         \param to_dimension Dimension of desired adjacencies
00584         \param create_if_missing If true, MB will create any entities of the specfied dimension
00585         which have not yet been created (only useful when <em>to_dimension <
00586        dim(*from_entities)</em>) \param adj_entities STL vector to which adjacent entities are
00587        appended. \param operation_type Enum of INTERSECT or UNION.  Defines whether to take the
00588        intersection or union of the set of adjacencies recovered for the from_entities.
00589 
00590         The adjacent entities in vector <em>adjacencies</em> are not in any particular
00591         order.
00592 
00593         Example: \code
00594         std::vector<EntityHandle> adjacencies, from_entities = {hex1, hex2};
00595           // generate all edges for these two hexes
00596           get_adjacencies( from_entities, 2, 1, true, adjacencies, Interface::UNION);
00597           adjacencies.clear();
00598             // now find the edges common to both hexes
00599             get_adjacencies( from_entities, 2, 1, false, adjacencies, Interface::INTERSECT);
00600             \endcode
00601     */
00602 
00603     virtual ErrorCode get_adjacencies( const EntityHandle* from_entities, const int num_entities,
00604                                        const int to_dimension, const bool create_if_missing,
00605                                        std::vector< EntityHandle >& adj_entities,
00606                                        const int operation_type = Interface::INTERSECT ) = 0;
00607 
00608     //! Get the adjacencies associated with a vector of entities to entities of a specfied
00609     //! dimension.
00610     /** Identical to vector-based get_adjacencies function, except results are returned in a
00611         range instead of a vector.
00612     */
00613     virtual ErrorCode get_adjacencies( const EntityHandle* from_entities, const int num_entities,
00614                                        const int to_dimension, const bool create_if_missing, Range& adj_entities,
00615                                        const int operation_type = Interface::INTERSECT ) = 0;
00616 
00617     //! Get the adjacencies associated with a range of entities to entities of a specfied dimension.
00618     /** Identical to vector-based get_adjacencies function, except "from" entities specified in a
00619         range instead of a vector.
00620     */
00621     virtual ErrorCode get_adjacencies( const Range& from_entities, const int to_dimension, const bool create_if_missing,
00622                                        Range& adj_entities, const int operation_type = Interface::INTERSECT ) = 0;
00623 
00624     //! Adds adjacencies between "from" and "to" entities.
00625     /** \param from_handle Entities on which the adjacencies are placed
00626         \param to_handles Vector of entities referenced by new adjacencies added to
00627        <em>from_handle</em> \param num_handles Number of entities in <em>to_handles</em> \param
00628        both_ways If true, add the adjacency information in both directions; if false, adjacencies
00629        are added only to <em>from_handle</em>
00630     */
00631     virtual ErrorCode add_adjacencies( const EntityHandle from_handle, const EntityHandle* to_handles,
00632                                        const int num_handles, bool both_ways ) = 0;
00633 
00634     //! Adds adjacencies; same as vector-based, but with range instead
00635     virtual ErrorCode add_adjacencies( const EntityHandle from_handle, Range& adjacencies, bool both_ways ) = 0;
00636 
00637     //! Removes adjacencies between handles.
00638     /** Adjacencies in both directions are removed.
00639         \param from_handle Entity from which adjacencies are being removed.
00640         \param to_handles Entities to which adjacencies are being removed.
00641         \param num_handles Number of handles in <em>to_handles</em>
00642     */
00643     virtual ErrorCode remove_adjacencies( const EntityHandle from_handle, const EntityHandle* to_handles,
00644                                           const int num_handles ) = 0;
00645 
00646     /**\brief Get a ptr to adjacency lists
00647      * Get a pointer to adjacency lists.  These lists are std::vector<EntityHandle>, which are
00648      * pointed to by adjs[i].  Adjacencies are not guaranteed to be in order of increasing
00649      * dimension.  Only a const version of this function is given, because adjacency data is managed
00650      * more carefully in MOAB and should be treated as read-only by applications.  If adjacencies
00651      * have not yet been initialized, adjs_ptr will be NULL (i.e. adjs_ptr == NULL).  There may also
00652      * be NULL entries for individual entities, i.e. adjs_ptr[i] == NULL. \param iter Iterator to
00653      * beginning of entity range desired \param end End iterator for which adjacencies are requested
00654      * \param adjs_ptr Pointer to pointer to const std::vector<EntityHandle>; each member of that
00655      * array is the vector of adjacencies for this entity \param count Number of entities in the
00656      * contiguous chunk starting from *iter
00657      */
00658     virtual ErrorCode adjacencies_iterate( Range::const_iterator iter, Range::const_iterator end,
00659                                            const std::vector< EntityHandle >**& adjs_ptr, int& count ) = 0;
00660     /**@}*/
00661 
00662     //! Enumerated type used in get_adjacencies() and other functions
00663     enum
00664     {
00665         INTERSECT,
00666         UNION
00667     };
00668 
00669     /** \name Getting entities */
00670 
00671     /**@{*/
00672 
00673     //! Retrieves all entities of a given topological dimension in the database or meshset.
00674     /** Appends entities to list passed in.
00675         \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
00676         \param dimension Topological dimension of entities desired.
00677         \param entities Range in which entities of dimension <em>dimension</em> are returned.
00678         \param recursive If true, meshsets containing meshsets are queried recursively.  Returns
00679                          the contents of meshsets, but not the meshsets themselves if true.
00680 
00681         Example: \code
00682           // get 1d (edge) elements in the entire mesh
00683           Range edges;
00684           get_entities_by_dimension( 0, 1, edges );
00685           \endcode
00686     */
00687     virtual ErrorCode get_entities_by_dimension( const EntityHandle meshset, const int dimension, Range& entities,
00688                                                  const bool recursive = false ) const = 0;
00689 
00690     //! Retrieves all entities of a given topological dimension in the database or meshset.
00691     /** Appends entities to list passed in.
00692         \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
00693         \param dimension Topological dimension of entities desired.
00694         \param entities Range in which entities of dimension <em>dimension</em> are returned.
00695         \param recursive If true, meshsets containing meshsets are queried recursively.  Returns
00696                          the contents of meshsets, but not the meshsets themselves if true.
00697 
00698         Example: \code
00699           // get 1d (edge) elements in the entire mesh
00700           Range edges;
00701           get_entities_by_dimension( 0, 1, edges );
00702           \endcode
00703     */
00704     virtual ErrorCode get_entities_by_dimension( const EntityHandle meshset, const int dimension,
00705                                                  std::vector< EntityHandle >& entities,
00706                                                  const bool recursive = false ) const = 0;
00707 
00708     //! Retrieve all entities of a given type in the database or meshset.
00709     /** Appends entities to list passed in.
00710         \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
00711         \param type Type of entities to be returned
00712         \param entities Range in which entities of type <em>type</em> are returned.
00713         \param recursive If true, meshsets containing meshsets are queried recursively.  Returns
00714                          the contents of meshsets, but not the meshsets themselves.  Specifying
00715                          both recursive=true and type=MBENTITYSET is an error, as it would always
00716                          result in an empty list.
00717 
00718         Example: \code
00719           // get the quadrilateral elements in meshset
00720           Range quads;
00721           get_entities_by_type( meshset, MBQUAD, quads );
00722           \endcode
00723     */
00724     virtual ErrorCode get_entities_by_type( const EntityHandle meshset, const EntityType type, Range& entities,
00725                                             const bool recursive = false ) const = 0;
00726 
00727     //! Retrieve all entities of a given type in the database or meshset.
00728     /** Appends entities to list passed in.
00729         \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
00730         \param type Type of entities to be returned
00731         \param entities Range in which entities of type <em>type</em> are returned.
00732         \param recursive If true, meshsets containing meshsets are queried recursively.  Returns
00733                          the contents of meshsets, but not the meshsets themselves.  Specifying
00734                          both recursive=true and type=MBENTITYSET is an error, as it would always
00735                          result in an empty list.
00736 
00737         Example: \code
00738           // get the quadrilateral elements in meshset
00739           Range quads;
00740           get_entities_by_type( meshset, MBQUAD, quads );
00741           \endcode
00742     */
00743     virtual ErrorCode get_entities_by_type( const EntityHandle meshset, const EntityType type,
00744                                             std::vector< EntityHandle >& entities,
00745                                             const bool recursive = false ) const = 0;
00746 
00747     //! Retrieve entities in the database or meshset which have any or all of the tag(s) and
00748     //! (optionally) value(s) specified.
00749     /** \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
00750         \param type Type of entities to be returned
00751         \param tag_handles Vector of tag handles entities must have
00752         \param values Vector of pointers to values of tags in <em>tag_handles</em>
00753         \param num_tags Number of tags and values in <em>tag_handles</em> and <em>values</em>
00754         \param entities Range in which entities are returned.
00755         \param condition Boolean condition, either Interface::UNION or Interface::INTERSECT
00756         \param recursive If true, meshsets containing meshsets are queried recursively.  Returns
00757                          the contents of meshsets, but not the meshsets themselves.  Specifying
00758                          both recursive=true and type=MBENTITYSET is an error, as it would always
00759                          result in an empty list.
00760 
00761         If Interface::UNION is specified as the condition, entities with <em>any</em> of the tags
00762         and values specified are returned.  If Interface::INTERSECT is specified, only entities with
00763         <em>all</em> of the tags/values are returned.
00764 
00765         If <em>values</em> is NULL, entities with the specified tags and any corresponding values
00766        are returned.  Note that if <em>values</em> is non-NULL, it is a vector of <em>pointers</em>
00767        to tag values.
00768 
00769         Example: \code
00770           // get the dirichlet sets in a mesh
00771           Range dir_sets;
00772           Tag dir_tag;
00773           tag_get_handle(DIRICHLET_SET_TAG_NAME, dir_tag, 1, MB_TYPE_INTEGER);
00774           get_entities_by_type_and_tag(0, MBENTITYSET, &dir_tag, NULL, 1, dir_sets,
00775           Interface::UNION);
00776           \endcode
00777     */
00778     virtual ErrorCode get_entities_by_type_and_tag( const EntityHandle meshset, const EntityType type,
00779                                                     const Tag* tag_handles, const void* const* values,
00780                                                     const int num_tags, Range& entities,
00781                                                     const int condition  = Interface::INTERSECT,
00782                                                     const bool recursive = false ) const = 0;
00783 
00784     //! Returns all entities in the data base or meshset, in a range (order not preserved)
00785     /** Appends entities to list passed in.
00786         \param meshset Meshset whose entities are being queried (zero if query is for the entire
00787        mesh). \param entities Range in which entities are returned. \param recursive If true,
00788        meshsets containing meshsets are queried recursively.  Returns the contents of meshsets, but
00789        not the meshsets themselves if true.
00790 
00791         Example: \code
00792         Range entities;
00793           // get all non-meshset entities in meshset, including in contained meshsets
00794           get_entities_by_handle(meshset, entities, true);
00795           \endcode
00796     */
00797     virtual ErrorCode get_entities_by_handle( const EntityHandle meshset, Range& entities,
00798                                               const bool recursive = false ) const = 0;
00799 
00800     //! Returns all entities in the data base or meshset, in a vector (order preserved)
00801     /** Appends entities to list passed in.
00802         \param meshset Meshset whose entities are being queried (zero if query is for the entire
00803        mesh). \param entities STL vector in which entities are returned. \param recursive If true,
00804        meshsets containing meshsets are queried recursively.  Returns the contents of meshsets, but
00805        not the meshsets themselves if true.
00806 
00807         Example: \code
00808         std::vector<EntityHandle> entities;
00809           // get all non-meshset entities in meshset, including in contained meshsets
00810           get_entities_by_handle(meshset, entities, true);
00811           \endcode
00812     */
00813     virtual ErrorCode get_entities_by_handle( const EntityHandle meshset, std::vector< EntityHandle >& entities,
00814                                               const bool recursive = false ) const = 0;
00815 
00816     //! Return the number of entities of given dimension in the database or meshset
00817     /** \param meshset Meshset whose entities are being queried (zero if query is for the entire
00818        mesh). \param dimension Dimension of entities desired. \param num_entities Number of entities
00819        of the given dimension \param recursive If true, meshsets containing meshsets are queried
00820        recursively.  Returns the contents of meshsets, but not the meshsets themselves if true.
00821     */
00822     virtual ErrorCode get_number_entities_by_dimension( const EntityHandle meshset, const int dimension,
00823                                                         int& num_entities, const bool recursive = false ) const = 0;
00824 
00825     //! Retrieve the number of entities of a given type in the database or meshset.
00826     /** Identical to get_entities_by_dimension, except returns number instead of entities
00827         \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
00828         \param type Type of entities to be returned
00829         \param num_entities Number of entities of type <em>type</em>
00830         \param recursive If true, meshsets containing meshsets are queried recursively.  Returns
00831                          the contents of meshsets, but not the meshsets themselves.  Specifying
00832                          both recursive=true and type=MBENTITYSET is an error, as it would always
00833                          result in an empty list.
00834     */
00835     virtual ErrorCode get_number_entities_by_type( const EntityHandle meshset, const EntityType type, int& num_entities,
00836                                                    const bool recursive = false ) const = 0;
00837 
00838     //! Retrieve number of entities in the database or meshset which have any or all of the
00839     //! tag(s) and (optionally) value(s) specified.
00840     /** Identical to get_entities_by_type_and_tag, except number instead of entities are returned
00841         \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
00842         \param type Type of entities to be returned
00843         \param tag_handles Vector of tag handles entities must have
00844         \param values Vector of pointers to values of tags in <em>tag_handles</em>
00845         \param num_tags Number of tags and values in <em>tag_handles</em> and <em>values</em>
00846         \param num_entities Range in which number of entities are returned.
00847         \param recursive If true, meshsets containing meshsets are queried recursively.  Returns
00848                          the contents of meshsets, but not the meshsets themselves.  Specifying
00849                          both recursive=true and type=MBENTITYSET is an error, as it would always
00850                          result in an empty list.
00851     */
00852     virtual ErrorCode get_number_entities_by_type_and_tag( const EntityHandle meshset, const EntityType type,
00853                                                            const Tag* tag_handles, const void* const* values,
00854                                                            const int num_tags, int& num_entities,
00855                                                            const int condition  = Interface::INTERSECT,
00856                                                            const bool recursive = false ) const = 0;
00857 
00858     //! Returns number of entities in the data base or meshset
00859     /** Identical to get-entities_by_handle, except number instead of entities are returned
00860         \param meshset Meshset whose entities are being queried (zero if query is for the entire
00861        mesh). \param num_entities Range in which num_entities are returned. \param recursive If
00862        true, meshsets containing meshsets are queried recursively.  Returns the contents of
00863        meshsets, but not the meshsets themselves if true.
00864     */
00865     virtual ErrorCode get_number_entities_by_handle( const EntityHandle meshset, int& num_entities,
00866                                                      const bool recursive = false ) const = 0;
00867 
00868     /**@}*/
00869 
00870     /** \name Mesh modification */
00871 
00872     /**@{*/
00873 
00874     //! Create an element based on the type and connectivity.
00875     /** Create a new element in the database.  Vertices composing this element must already exist,
00876         and connectivity must be specified in canonical order for the given element type.  If
00877         connectivity vector is not correct for EntityType <em>type</em> (ie, a vector with
00878         3 vertices is passed in to make an MBQUAD), the function returns MB_FAILURE.
00879         \param type Type of element to create. (MBTET, MBTRI, MBKNIFE, etc.)
00880         \param connectivity 1d vector containing connectivity of element to create.
00881         \param num_vertices Number of vertices in element
00882         \param element_handle Handle representing the newly created element in the database.
00883 
00884         Example: \code
00885         EntityHandle quad_conn[] = {vertex0, vertex1, vertex2, vertex3};
00886         EntityHandle quad_handle = 0;
00887         create_element( MBQUAD, quad_conn, 4, quad_handle ); \endcode
00888     */
00889     virtual ErrorCode create_element( const EntityType type, const EntityHandle* connectivity, const int num_vertices,
00890                                       EntityHandle& element_handle ) = 0;
00891 
00892     //! Creates a vertex with the specified coordinates.
00893     /**
00894        \param coordinates Array that has 3 doubles in it.
00895        \param entity_handle EntityHandle representing the newly created vertex in the database.
00896 
00897        Example: \code
00898        double coordinates[] = {1.034, 23.23, -0.432};
00899        EntityHandle new_handle = 0;
00900        create_vertex( coordinates, entity_handle ); \endcode
00901     */
00902     virtual ErrorCode create_vertex( const double coordinates[3], EntityHandle& entity_handle ) = 0;
00903 
00904     //! Create a set of vertices with the specified coordinates
00905     /**
00906        \param coordinates Array that has 3*n doubles in it.
00907        \param nverts Number of vertices to create
00908        \param entity_handles Range passed back with new vertex handles
00909     */
00910     virtual ErrorCode create_vertices( const double* coordinates, const int nverts, Range& entity_handles ) = 0;
00911 
00912     //! Merge two entities into a single entity
00913     /** Merge two entities into a single entities, with <em>entity_to_keep</em> receiving
00914         adjacencies that were on <em>entity_to_remove</em>.
00915         \param entity_to_keep Entity to be kept after merge
00916         \param entity_to_remove Entity to be merged into <em>entity_to_keep</em>
00917         \param auto_merge If false, <em>entity_to_keep</em> and <em>entity_to_remove</em> must share
00918         the same lower-dimensional entities; if true, MB tries to merge those entities automatically
00919         \param delete_removed_entity If true, <em>entity_to_remove</em> is deleted after merge is
00920        complete
00921     */
00922     virtual ErrorCode merge_entities( EntityHandle entity_to_keep, EntityHandle entity_to_remove, bool auto_merge,
00923                                       bool delete_removed_entity ) = 0;
00924 
00925     //! Removes entities in a vector from the data base.
00926     /** If any of the entities are contained in any meshsets, it is removed from those meshsets
00927         which were created with MESHSET_TRACK_OWNER option bit set.  Tags for <em>entity</em> are
00928         removed as part of this function.
00929         \param entities 1d vector of entities to delete
00930         \param num_entities Number of entities in 1d vector
00931     */
00932     virtual ErrorCode delete_entities( const EntityHandle* entities, const int num_entities ) = 0;
00933 
00934     //! Removes entities in a range from the data base.
00935     /** If any of the entities are contained in any meshsets, it is removed from those meshsets
00936         which were created with MESHSET_TRACK_OWNER option bit set.  Tags for <em>entity</em> are
00937         removed as part of this function.
00938         \param entities Range of entities to delete
00939     */
00940     virtual ErrorCode delete_entities( const Range& entities ) = 0;
00941 
00942     /**@}*/
00943 
00944     /** \name Information */
00945 
00946     /**@{*/
00947 
00948     //! List entities to standard output
00949     /** Lists all data pertaining to entities (i.e. vertex coordinates if vertices, connectivity if
00950         elements, set membership if set).  Useful for debugging, but output can become quite long
00951         for large databases.
00952     */
00953     virtual ErrorCode list_entities( const Range& entities ) const = 0;
00954 
00955     //! List entities, or number of entities in database, to standard output
00956     /** Lists data pertaining to entities to standard output.  If <em>entities</em> is NULL and
00957         <em>num_entities</em> is zero, lists only the number of entities of each type in the
00958         database.  If <em>entities</em> is NULL and <em>num_entities</em> is non-zero, lists all
00959         information for all entities in the database.
00960         \param entities 1d vector of entities to list
00961         \param num_entities Number of entities in 1d vector
00962     */
00963     virtual ErrorCode list_entities( const EntityHandle* entities, const int num_entities ) const = 0;
00964 
00965     //! List a single entity; no header printed
00966     /** Lists a single entity, including its connectivity and its adjacencies.
00967      *  No header is printed, because calling function might print information between header
00968      *  and information printed by this function.
00969      *  \param entity The entity to be listed.
00970      */
00971     virtual ErrorCode list_entity( const EntityHandle entity ) const = 0;
00972 
00973     //! Return information about the last error
00974     /** \param info std::string into which information on the last error is written.
00975      */
00976     virtual ErrorCode get_last_error( std::string& info ) const = 0;
00977 
00978     //! Return string representation of given error code
00979     /** \param code Error code for which string is wanted
00980      */
00981     virtual std::string get_error_string( const ErrorCode code ) const = 0;
00982 
00983     /**\brief Calculate amount of memory used to store MOAB data
00984      *
00985      * This function calculates the amount of memory used to store
00986      * MOAB data.
00987      *
00988      * There are two possible values for each catagory of memory use.
00989      * The exact value and the amortized value.  The exact value is the
00990      * amount of memory used to store the data for the specified entities.
00991      * The amortized value includes the exact value and an amortized
00992      * estimate of the memory consumed in overhead for storing the values
00993      * (indexing structures, access structures, etc.)
00994      *
00995      * Note: If ent_array is NULL and total_amortized_storage is *not* NULL,
00996      *       the total memory used by MOAB for storing data all will be
00997      *       returned in the address pointed to by total_amortized_storage.
00998      *
00999      *\param ent_array Array of entities for which to estimate the memory use.
01000      *                 If NULL, estimate is done for all entities.
01001      *\param num_ents The length of ent_array.  Not used if ent_rray is NULL.
01002      *\param total_(amortized_)storage The sum of the memory entity, adjacency,
01003      *                   and all tag storage.
01004      *\param (amortized_)entity_storage The storage for the entity definitions
01005      *                   (connectivity arrays for elements, coordinates for
01006      *                   vertices, list storage within sets, etc.)
01007      *\param (amortized_)adjacency_storage The storage for adjacency data.
01008      *\param tag_array   An array of tags for which to calculate the memory use.
01009      *\param num_tags    The lenght of tag_array
01010      *\param (amortized_)tag_storage If tag_array is not NULL, then one value
01011      *                   for each tag specifying the memory used for storing
01012      *                   that tag.  If tag_array is NULL and this value is not,
01013      *                   the location at which to store the total memory used
01014      *                   for all tags.
01015      */
01016     virtual void estimated_memory_use(
01017         const EntityHandle* ent_array = 0, unsigned long num_ents = 0, unsigned long long* total_storage = 0,
01018         unsigned long long* total_amortized_storage = 0, unsigned long long* entity_storage = 0,
01019         unsigned long long* amortized_entity_storage = 0, unsigned long long* adjacency_storage = 0,
01020         unsigned long long* amortized_adjacency_storage = 0, const Tag* tag_array = 0, unsigned num_tags = 0,
01021         unsigned long long* tag_storage = 0, unsigned long long* amortized_tag_storage = 0 ) = 0;
01022 
01023     /**\brief Calculate amount of memory used to store MOAB data
01024      *
01025      * This function calculates the amount of memory used to store
01026      * MOAB data.
01027      *
01028      * There are two possible values for each catagory of memory use.
01029      * The exact value and the amortized value.  The exact value is the
01030      * amount of memory used to store the data for the specified entities.
01031      * The amortized value includes the exact value and an amortized
01032      * estimate of the memory consumed in overhead for storing the values
01033      * (indexing structures, access structures, etc.)
01034      *
01035      *\param ents        Entities for which to estimate the memory use.
01036      *\param total_(amortized_)storage The sum of the memory entity, adjacency,
01037      *                   and all tag storage.
01038      *\param (amortized_)entity_storage The storage for the entity definitions
01039      *                   (connectivity arrays for elements, coordinates for
01040      *                   vertices, list storage within sets, etc.)
01041      *\param (amortized_)adjacency_storage The storage for adjacency data.
01042      *\param tag_array   An array of tags for which to calculate the memory use.
01043      *\param num_tags    The lenght of tag_array
01044      *\param (amortized_)tag_storage If tag_array is not NULL, then one value
01045      *                   for each tag specifying the memory used for storing
01046      *                   that tag.  If tag_array is NULL and this value is not,
01047      *                   the location at which to store the total memory used
01048      *                   for all tags.
01049      */
01050     virtual void estimated_memory_use( const Range& ents, unsigned long long* total_storage = 0,
01051                                        unsigned long long* total_amortized_storage     = 0,
01052                                        unsigned long long* entity_storage              = 0,
01053                                        unsigned long long* amortized_entity_storage    = 0,
01054                                        unsigned long long* adjacency_storage           = 0,
01055                                        unsigned long long* amortized_adjacency_storage = 0, const Tag* tag_array = 0,
01056                                        unsigned num_tags = 0, unsigned long long* tag_storage = 0,
01057                                        unsigned long long* amortized_tag_storage = 0 ) = 0;
01058     /**@}*/
01059 
01060     /** \name Higher-order elements */
01061 
01062     /**@{*/
01063 
01064     //! function object for recieving events from MB of higher order nodes added to entities
01065     class HONodeAddedRemoved
01066     {
01067       public:
01068         //! Constructor
01069         HONodeAddedRemoved() {}
01070 
01071         //! Destructor
01072         virtual ~HONodeAddedRemoved() {}
01073 
01074         //! node_added called when a node was added to an element's connectivity array
01075         //! note: connectivity array of element may be incomplete (corner nodes will exist always)
01076         /**
01077          * \param node Node being added
01078          * \param element Element node is being added to
01079          */
01080         virtual void node_added( EntityHandle node, EntityHandle element ) = 0;
01081 
01082         //! node_added called when a node was added to an element's connectivity array
01083         //! note: connectivity array of element may be incomplete (corner nodes will exist always)
01084         /**
01085          * \param node Node being removed.
01086          */
01087         virtual void node_removed( EntityHandle node ) = 0;
01088     };
01089 
01090     //! Convert entities to higher-order elements by adding mid nodes
01091     /** This function causes MB to create mid-nodes on all edges, faces, and element interiors
01092         for all entities in <em>meshset</em>.  Higher order nodes appear in an element's
01093        connectivity array according to the algorithm described in the documentation for Mesh.  If
01094         <em>HONodeAddedRemoved</em> function is input, this function is called to notify the
01095        application of nodes being added/removed from the mesh. \param meshset The set of entities
01096        being converted \param mid_edge If true, mid-edge nodes are created \param mid_face If true,
01097        mid-face nodes are created \param mid_region If true, mid-element nodes are created \param
01098        function_object If non-NULL, the node_added or node_removed functions on this object are
01099        called when nodes are added or removed from an entity, respectively
01100     */
01101     virtual ErrorCode convert_entities( const EntityHandle meshset, const bool mid_edge, const bool mid_face,
01102                                         const bool mid_region, HONodeAddedRemoved* function_object = 0 ) = 0;
01103 
01104     //! Returns the side number, in canonical ordering, of <em>child</em> with respect to
01105     //! <em>parent</em>
01106     /** Given a parent and child entity, returns the canonical ordering information side number,
01107        sense, and offset of <em>child</em> with respect to <em>parent</em>.  This function returns
01108         MB_FAILURE if <em>child</em> is not related to <em>parent</em>.  This function does *not*
01109         create adjacencies between <em>parent</em> and <em>child</em>.
01110         \param parent Parent entity to be compared
01111         \param child Child entity to be compared
01112         \param side_number Side number in canonical ordering of <em>child</em> with respect to
01113         <em>parent</em>
01114         \param sense Sense of <em>child</em> with respect to <em>parent</em>, assuming ordering of
01115         <em>child</em> as given by get_connectivity called on <em>child</em>; sense is 1, -1
01116         for forward/reverse sense, resp.
01117         \param offset Offset between first vertex of <em>child</em> and first vertex of side
01118         <em>side_number</em> on <em>parent</em>
01119     */
01120     virtual ErrorCode side_number( const EntityHandle parent, const EntityHandle child, int& side_number, int& sense,
01121                                    int& offset ) const = 0;
01122 
01123     //! Find the higher-order node on a subfacet of an entity
01124     /** Given an entity and the connectivity and type of one of its subfacets, find the
01125         high order node on that subfacet, if any.  The number of vertices in <em>subfacet_conn</em>
01126         is derived from <em>subfacet_type</em> and the canonical numbering for that type.
01127         \param parent_handle The element whose subfacet is being queried
01128         \param subfacet_conn The connectivity of the subfacet being queried
01129         \param subfacet_type The type of subfacet being queried
01130         \param high_order_node If the subfacet has a high-order node defined on
01131        <em>parent_handle</em>, the handle for that node.
01132     */
01133     virtual ErrorCode high_order_node( const EntityHandle parent_handle, const EntityHandle* subfacet_conn,
01134                                        const EntityType subfacet_type, EntityHandle& high_order_node ) const = 0;
01135 
01136     //! Return the handle of the side element of a given dimension and index
01137     /** Given a parent entity and a target dimension and side number, return the handle of
01138         the entity corresponding to that side.  If an entity has not been created to represent
01139         that side, one is not created by this function, and zero is returned in
01140        <em>target_entity</em>. \param source_entity The entity whose side is being queried. \param
01141        dim The topological dimension of the side being queried. \param side_number The canonical
01142        index of the side being queried. \param target_entity The handle of the entity representing
01143        this side, if any.
01144     */
01145     virtual ErrorCode side_element( const EntityHandle source_entity, const int dim, const int side_number,
01146                                     EntityHandle& target_entity ) const = 0;
01147 
01148     /**@}*/
01149 
01150     /** \name Tags */
01151 
01152     /**@{*/
01153 
01154     /**\brief Get a tag handle, possibly creating the tag
01155      *
01156      * Get a handle used to associate application-defined values
01157      * with MOAB entities.  If the tag does not already exist then
01158      * \c flags should contain exactly one of \c MB_TAG_SPARSE,
01159      * \c MB_TAG_DENSE, \c MB_TAG_MESH unless \c type is MB_TYPE_BIT,
01160      * which implies \c MB_TAG_BIT storage.
01161      * .
01162      *\param name          The tag name
01163      *\param size          Tag size as number of values of of data type per entity
01164      *                     (or number of bytes if \c MB_TAG_BYTES is passed in flags).  If \c
01165      *MB_TAG_VARLEN is specified, this value is taken to be the size of the default value if one is
01166      *specified and is otherwise ignored. \param type          The type of the data (used for IO)
01167      *\param tag_handle    Output: the resulting tag handle.
01168      *\param flags         Bitwise OR of values from TagType
01169      *\param default_value Optional default value for tag.
01170      *\param created       Optional returned boolean indicating that the tag
01171      *                     was created.
01172      *\return - \c MB_ALREADY_ALLOCATED     if tag exists and \c MB_TAG_EXCL is specified, or
01173      *default values do not match (and \c MB_TAG_ANY or \c MB_TAG_DFTOK not specified).
01174      *        - \c MB_TAG_NOT_FOUND         if tag does not exist and \c MB_TAG_CREAT is not
01175      *specified
01176      *        - \c MB_INVALID_SIZE          if tag value size is not a multiple of the size of the
01177      *data type (and \c MB_TAG_ANY not specified).
01178      *        - \c MB_TYPE_OUT_OF_RANGE     invalid or inconsistent parameter
01179      *        - \c MB_VARIABLE_DATA_LENGTH  if \c MB_TAG_VARLEN and \c default_value is non-null and
01180      *                                      \c default_value_size is not specified.
01181      *
01182      *\NOTE A call to tag_get_handle that includes a default value will fail
01183      * if the tag already exists with a different default value.  A call without
01184      * a default value will succeed if the tag already exists, regardless of
01185      * whether or not the existing tag has a default value.
01186      *
01187      * Examples:
01188      *
01189      * Retrieve a handle for an existing tag, returning a non-success error
01190      * code if the tag does not exist or does not store 1 integer value per
01191      * entity:
01192      *\code
01193      * Tag git_tag;
01194      * mb.tag_get_handle( GLOBAL_ID_TAG_NAME, 1, MB_TYPE_INTEGER, gid_tag );
01195      * \endcode
01196      * Get the tag handle, or create it as a dense tag if it does not already
01197      * exist:
01198      *\code
01199      * Tag gid_tag;
01200      * mb.tag_get_handle( GLOBAL_ID_TAG_NAME, 1, MB_TYPE_INTEGER, gid_tag, MB_TAG_CREAT|MB_TAG_BIT
01201      *); \endcode Create the tag or *fail* if it already exists: \code Tag gid_tag;
01202      * mb.tag_get_handle( GLOBAL_ID_TAG_NAME, 1, MB_TYPE_INTEGER, gid_tag, MB_TAG_EXCL|MB_TAG_DENSE
01203      *); \endcode Get an existing variable length tag, failing if it does not exist or is not
01204      *variable-length or does not contain double values. \code Tag vtag; mb.tag_get_handle(
01205      *tag_name, 0, MB_TYPE_DOUBLE, vtag ); \endcode Get the same variable-length tag, but create it
01206      *with a default value if it doesn't exist.  Note that if the tag already exists this call will
01207      *return a non-success error code if the existing tag has a different default value. \code Tag
01208      *vtag; const double default_val = M_PI; const int def_val_len = 1; mb.tag_get_handle( tag_name,
01209      *def_val_len, MB_TYPE_DOUBLE, vtag, MB_TAG_SPARSE|MB_TAG_VARLEN|MB_TAG_CREAT, &default_val );
01210      * \endcode
01211      */
01212     virtual ErrorCode tag_get_handle( const char* name, int size, DataType type, Tag& tag_handle, unsigned flags = 0,
01213                                       const void* default_value = 0, bool* created = 0 ) = 0;
01214 
01215     /**\brief same as non-const version, except that MB_TAG_CREAT flag is ignored. */
01216     virtual ErrorCode tag_get_handle( const char* name, int size, DataType type, Tag& tag_handle, unsigned flags = 0,
01217                                       const void* default_value = 0 ) const = 0;
01218 
01219     //! Get the name of a tag corresponding to a handle
01220     /** \param tag_handle Tag you want the name of.
01221         \param tag_name Name string for <em>tag_handle</em>.
01222     */
01223     virtual ErrorCode tag_get_name( const Tag tag_handle, std::string& tag_name ) const = 0;
01224 
01225     /**\brief Gets the tag handle corresponding to a name
01226 
01227         If a tag of that name does not exist, returns MB_TAG_NOT_FOUND
01228         \param tag_name Name of the desired tag.
01229         \param tag_handle Tag handle corresponding to <em>tag_name</em>
01230     */
01231     virtual ErrorCode tag_get_handle( const char* tag_name, Tag& tag_handle ) const = 0;
01232 
01233     //! Get the size of the specified tag in bytes
01234     /** Get the size of the specified tag, in bytes (MB_TAG_SPARSE, MB_TAG_DENSE, MB_TAG_MESH)
01235         \note always returns 1 for bit tags.
01236         \param tag Handle of the desired tag.
01237         \param bytes_per_tag Size of the specified tag
01238         \return - MB_TAG_NOT_FOUND for invalid tag handles
01239                 - MB_VARIABLE_DATA_LENGTH for variable-length tags
01240                 - MB_SUCCESS otherwise
01241     */
01242     virtual ErrorCode tag_get_bytes( const Tag tag, int& bytes_per_tag ) const = 0;
01243 
01244     //! Get the array length of a tag
01245     /** Get the size of the specified tag, in as the number of values of
01246         the basic type (e.g. number of integer values for each tag value if
01247         the data type is MB_TYPE_INTEGER).  Gives number of bits for bit tags
01248         and is the same as \c tag_get_bytes for MB_TYPE_OPAQUE tags.
01249         \param tag Handle of the desired tag.
01250         \param length Size of the specified tag
01251         \return - MB_TAG_NOT_FOUND for invalid tag handles
01252                 - MB_VARIABLE_DATA_LENGTH for variable-length tags
01253                 - MB_SUCCESS otherwise
01254     */
01255     virtual ErrorCode tag_get_length( const Tag tag, int& length ) const = 0;
01256 
01257     //! Get the type of the specified tag
01258     /** Get the type of the specified tag
01259         \param tag Handle of the desired tag.
01260         \param tag_type Type of the specified tag
01261     */
01262     virtual ErrorCode tag_get_type( const Tag tag, TagType& tag_type ) const = 0;
01263 
01264     /** \brief Get data type of tag.
01265      *
01266      * Get the type of the tag data.  The tag is data is assumed to
01267      * be a vector of this type.  If the tag data vetcor contains
01268      * more than one value, then the tag size must be a multiple of
01269      * the size of this type.
01270      * \param tag  The tag
01271      * \param type The type of the specified tag (output).
01272      */
01273     virtual ErrorCode tag_get_data_type( const Tag tag, DataType& type ) const = 0;
01274 
01275     //! Get the default value of the specified tag
01276     /** Get the default value of the specified tag
01277         \param tag Handle of the desired tag.
01278         \param def_value Pointer to memory where default value of the specified tag is written
01279         \return - MB_ENTITY_NOT_FOUND If no default value is set for tag.
01280                 - MB_SUCCESS          If success.
01281                 - MB_FAILURE          If <code>def_val</code> is NULL.
01282                 - MB_TAG_NOT_FOUND    If <code>tag_handle</code> is invalid.
01283     */
01284     virtual ErrorCode tag_get_default_value( const Tag tag, void* def_val ) const             = 0;
01285     virtual ErrorCode tag_get_default_value( Tag tag, const void*& def_val, int& size ) const = 0;
01286 
01287     //! Get handles for all tags defined in the mesh instance
01288     /** Get handles for all tags defined on the mesh instance.
01289         \param tag_handles STL vector of all tags
01290     */
01291     virtual ErrorCode tag_get_tags( std::vector< Tag >& tag_handles ) const = 0;
01292 
01293     //! Get handles for all tags defined on this entity
01294     /** Get handles for all tags defined on this entity; if zero, get all tags defined
01295         on mesh instance
01296         \param entity Entity for which you want tags
01297         \param tag_handles STL vector of all tags defined on <em>entity</em>
01298     */
01299     virtual ErrorCode tag_get_tags_on_entity( const EntityHandle entity, std::vector< Tag >& tag_handles ) const = 0;
01300 
01301     //! Get the value of the indicated tag on the specified entities in the specified vector
01302     /** Get the value of the indicated tag on the specified entities; <em>tag_data</em> must contain
01303         enough space (i.e. tag_size*num_entities bytes) to hold all tag data.  MOAB does
01304        <em>not</em> check whether this space is available before writing to it. \note For bit tags,
01305        tag_data must contain one byte per entity.  For each entity, the corresponding byte will
01306        contain the tag bits in the lower bit positions and zero bits in the higher. \param
01307        tag_handle Tag whose values are being queried. \param entity_handles 1d vector of entity
01308        handles whose tag values are being queried \param num_entities Number of entities in 1d
01309        vector of entity handles \param tag_data Pointer to memory into which tag data will be
01310        written
01311     */
01312     virtual ErrorCode tag_get_data( const Tag tag_handle, const EntityHandle* entity_handles, int num_entities,
01313                                     void* tag_data ) const = 0;
01314 
01315     //! Get the value of the indicated tag on the specified entities in the specified range
01316     /** Identical to previous function, except entities are specified using a range instead of a 1d
01317        vector. \param tag_handle Tag whose values are being queried. \param entity_handles Range of
01318        entity handles whose tag values are being queried \param tag_data Pointer to memory into
01319        which tag data will be written
01320     */
01321     virtual ErrorCode tag_get_data( const Tag tag_handle, const Range& entity_handles, void* tag_data ) const = 0;
01322 
01323     //! Set the value of the indicated tag on the specified entities in the specified vector
01324     /** Set the value of the indicated tag on the specified entities; <em>tag_data</em> contains the
01325         values, <em>one value per entity in <em>entity_handles</em></em>.
01326         \note For bit tags, tag_data must contain one byte per entity.  For each
01327               entity, the tag bits will be read from the lower bits of the
01328               corresponding byte.
01329         \param tag_handle Tag whose values are being set
01330         \param entity_handles 1d vector of entity handles whose tag values are being set
01331         \param num_entities Number of entities in 1d vector of entity handles
01332         \param tag_data Pointer to memory holding tag values to be set, <em>one entry per entity
01333        handle</em>
01334     */
01335     virtual ErrorCode tag_set_data( Tag tag_handle, const EntityHandle* entity_handles, int num_entities,
01336                                     const void* tag_data ) = 0;
01337 
01338     //! Set the value of the indicated tag on the specified entities in the specified range
01339     /** Identical to previous function, except entities are specified using a range instead of a 1d
01340        vector. \param tag_handle Tag whose values are being set \param entity_handles Range of
01341        entity handles whose tag values are being set \param tag_data Pointer to memory holding tag
01342        values to be set, <em>one entry per entity handle</em>
01343     */
01344     virtual ErrorCode tag_set_data( Tag tag_handle, const Range& entity_handles, const void* tag_data ) = 0;
01345 
01346     /**\brief Get pointers to tag data
01347      *
01348      * For a tag, get the values for a list of passed entity handles.
01349      *\note  This function may not be used for bit tags.
01350      *\param tag_handle     The tag
01351      *\param entity_handles An array of entity handles for which to retreive tag values.
01352      *\param num_entities   The length of the 'entity_handles' array.
01353      *\param tag_data       An array of 'const void*'.  Array must be at least
01354      *                      'num_entitities' long.  Array is populated (output)
01355      *                      with pointers to the internal storage for the
01356      *                      tag value corresponding to each entity handle.
01357      *\param tag_sizes      The length of each tag value.  Optional for
01358      *                      fixed-length tags.  Required for variable-length tags.
01359      */
01360     virtual ErrorCode tag_get_by_ptr( const Tag tag_handle, const EntityHandle* entity_handles, int num_entities,
01361                                       const void** tag_data, int* tag_sizes = 0 ) const = 0;
01362 
01363     /**\brief Get pointers to tag data
01364      *
01365      * For a tag, get the values for a list of passed entity handles.
01366      *\note  This function may not be used for bit tags.
01367      *\param tag_handle     The tag
01368      *\param entity_handles The entity handles for which to retreive tag values.
01369      *\param tag_data       An array of 'const void*'.  Array is populated (output)
01370      *                      with pointers to the internal storage for the
01371      *                      tag value corresponding to each entity handle.
01372      *\param tag_sizes      The length of each tag value.  Optional for
01373      *                      fixed-length tags.  Required for variable-length tags.
01374      */
01375     virtual ErrorCode tag_get_by_ptr( const Tag tag_handle, const Range& entity_handles, const void** tag_data,
01376                                       int* tag_sizes = 0 ) const = 0;
01377 
01378     /**\brief Set tag data given an array of pointers to tag values.
01379      *
01380      * For a tag, set the values for a list of passed entity handles.
01381      *\note  This function may not be used for bit tags.
01382      *\param tag_handle     The tag
01383      *\param entity_handles An array of entity handles for which to set tag values.
01384      *\param num_entities   The length of the 'entity_handles' array.
01385      *\param tag_data       An array of 'const void*'.  Array must be at least
01386      *                      'num_entitities' long.  Array is expected to
01387      *                      contain pointers to tag values for the corresponding
01388      *                      EntityHandle in 'entity_handles'.
01389      *\param tag_sizes      The length of each tag value.  Optional for
01390      *                      fixed-length tags.  Required for variable-length tags.
01391      */
01392     virtual ErrorCode tag_set_by_ptr( Tag tag_handle, const EntityHandle* entity_handles, int num_entities,
01393                                       void const* const* tag_data, const int* tag_sizes = 0 ) = 0;
01394 
01395     /**\brief Set tag data given an array of pointers to tag values.
01396      *
01397      * For a tag, set the values for a list of passed entity handles.
01398      *\note  This function may not be used for bit tags.
01399      *\param tag_handle     The tag
01400      *\param entity_handles The entity handles for which to set tag values.
01401      *\param tag_data       An array of 'const void*'.  Array is expected to
01402      *                      contain pointers to tag values for the corresponding
01403      *                      EntityHandle in 'entity_handles'.
01404      *\param tag_sizes      The length of each tag value.  Optional for
01405      *                      fixed-length tags.  Required for variable-length tags.
01406      */
01407     virtual ErrorCode tag_set_by_ptr( Tag tag_handle, const Range& entity_handles, void const* const* tag_data,
01408                                       const int* tag_sizes = 0 ) = 0;
01409 
01410     /**\brief Set tag data given value.
01411      *
01412      * For a tag, set the values for a list of passed entity handles to
01413      * the same, specified value.
01414      *
01415      *\param tag_handle     The tag
01416      *\param entity_handles The entity handles for which to set tag values.
01417      *\param tag_data       A pointer to the tag value.
01418      *\param tag_sizes      For variable-length tags, the length of the
01419      *                      tag value.  This argument will be ignored for
01420      *                      fixed-length tags.
01421      */
01422     virtual ErrorCode tag_clear_data( Tag tag_handle, const Range& entity_handles, const void* value,
01423                                       int value_size = 0 ) = 0;
01424 
01425     /**\brief Set tag data given value.
01426      *
01427      * For a tag, set the values for a list of passed entity handles to
01428      * the same, specified value.
01429      *
01430      *\param tag_handle     The tag
01431      *\param entity_handles The entity handles for which to set tag values.
01432      *\param tag_data       A pointer to the tag value.
01433      *\param tag_sizes      For variable-length tags, the length of the
01434      *                      tag value.  This argument will be ignored for
01435      *                      fixed-length tags.
01436      */
01437     virtual ErrorCode tag_clear_data( Tag tag_handle, const EntityHandle* entity_handles, int num_entity_handles,
01438                                       const void* value, int value_size = 0 ) = 0;
01439 
01440     //! Delete the data of a vector of entity handles and sparse tag
01441     /** Delete the data of a tag on a vector of entity handles.  Only sparse tag data are deleted
01442        with this function; dense tags are deleted by deleting the tag itself using tag_delete.
01443         \param tag_handle Handle of the (sparse) tag being deleted from entity
01444         \param entity_handles 1d vector of entity handles from which the tag is being deleted
01445         \param num_handles Number of entity handles in 1d vector
01446     */
01447     virtual ErrorCode tag_delete_data( Tag tag_handle, const EntityHandle* entity_handles, int num_handles ) = 0;
01448 
01449     //! Delete the data of a range of entity handles and sparse tag
01450     /** Delete the data of a tag on a range of entity handles.  Only sparse tag data are deleted
01451        with this function; dense tags are deleted by deleting the tag itself using tag_delete.
01452         \param tag_handle Handle of the (sparse) tag being deleted from entity
01453         \param entity_range Range of entities from which the tag is being deleted
01454     */
01455     virtual ErrorCode tag_delete_data( Tag tag_handle, const Range& entity_range ) = 0;
01456 
01457     /**\brief Access tag data via direct pointer into contiguous blocks
01458      *
01459      * Iteratively obtain direct access to contiguous blocks of tag
01460      * storage.  This function cannot be used with bit tags because
01461      * of the compressed bit storage.  This function cannot be used
01462      * with variable length tags because it does not provide a mechanism
01463      * to determine the length of the value for each entity.  This
01464      * function may be used with sparse tags, but if it is used, it
01465      * will return data for a single entity at a time.
01466      *
01467      *\param tag_handle  The handle of the tag for which to access data
01468      *\param iter        The first entity for which to return data.
01469      *\param end         One past the last entity for which data is desired.
01470      *\param count       The number of entities for which data was returned
01471      *\param data_ptr    Output: pointer to tag storage.
01472      *\param allocate    If true, space for this tag will be allocated, if not it wont
01473      *
01474      *\Note If this function is called for entities for which no tag value
01475      *      has been set, but for which a default value exists, it will
01476      *      force the allocation of explicit storage for each such entity
01477      *      even though MOAB would normally not explicitly store tag values
01478      *      for such entities.
01479      *
01480      *\Example:
01481      *\code
01482      * Range ents; // range to iterate over
01483      * Tag tag; // tag for which to access data
01484      * int bytes;
01485      * ErrorCode err = mb.tag_get_size( tag, bytes );
01486      * if (err) { ... }
01487      *
01488      * ...
01489      * Range::iterator iter = ents.begin();
01490      * while (iter != ents.end()) {
01491      *   int count;
01492      *    // get contiguous block of tag dat
01493      *   void* ptr;
01494      *   err = mb.tag_iterate( tag, iter, ents.end(), count, ptr );
01495      *   if (err) { ... }
01496      *    // do something with tag data
01497      *   process_Data( ptr, count );
01498      *    // advance to next block of data
01499      *   iter += count;
01500      * }
01501      *\endcode
01502      */
01503     virtual ErrorCode tag_iterate( Tag tag_handle, Range::const_iterator begin, Range::const_iterator end, int& count,
01504                                    void*& data_ptr, bool allocate = true ) = 0;
01505 
01506     //! Remove a tag from the database and delete all of its associated data
01507     /** Deletes a tag and all associated data.
01508      */
01509     virtual ErrorCode tag_delete( Tag tag_handle ) = 0;
01510 
01511     /**@}*/
01512 
01513     /** \name Sets */
01514 
01515     /**@{*/
01516 
01517     //! Create a new mesh set
01518     /** Create a new mesh set.  Meshsets can store entities ordered or unordered. A set can include
01519        entities at most once (MESHSET_SET) or more than once.  Meshsets can optionally track its
01520        members using adjacencies (MESHSET_TRACK_OWNER); if set, entities are deleted from tracking
01521        meshsets before being deleted.  This adds data to mesh entities, which can be expensive.
01522         \param options Options bitmask for the new meshset, possible values defined above
01523         \param ms_handle Handle for the meshset created
01524     */
01525     virtual ErrorCode create_meshset( const unsigned int options, EntityHandle& ms_handle, int start_id = 0 ) = 0;
01526 
01527     //! Empty a vector of mesh set
01528     /** Empty a mesh set.
01529         \param ms_handles 1d vector of handles of sets being emptied
01530         \param num_meshsets Number of entities in 1d vector
01531     */
01532     virtual ErrorCode clear_meshset( const EntityHandle* ms_handles, const int num_meshsets ) = 0;
01533 
01534     //! Empty a range of mesh set
01535     /** Empty a mesh set.
01536         \param ms_handles Range of handles of sets being emptied
01537     */
01538     virtual ErrorCode clear_meshset( const Range& ms_handles ) = 0;
01539 
01540     //! Get the options of a mesh set
01541     /** Get the options of a mesh set.
01542         \param ms_handle Handle for mesh set being queried
01543         \param options Bit mask in which mesh set options are returned
01544     */
01545     virtual ErrorCode get_meshset_options( const EntityHandle ms_handle, unsigned int& options ) const = 0;
01546 
01547     //! Set the options of a mesh set
01548     /** Set the options of a mesh set.
01549         \param ms_handle Handle for meshset whose options are being changed
01550         \param options Bit mask of options to be used
01551     */
01552     virtual ErrorCode set_meshset_options( const EntityHandle ms_handle, const unsigned int options ) = 0;
01553 
01554     //! Subtract meshsets
01555     /** Subtract <em>meshset2</em> from <em>meshset1</em>, placing the results in meshset1.
01556         \param meshset1 Mesh set being subtracted from, also used to pass back result
01557         \param meshset2 Mesh set being subtracted from <em>meshset1</em>
01558     */
01559     virtual ErrorCode subtract_meshset( EntityHandle meshset1, const EntityHandle meshset2 ) = 0;
01560 
01561     //! Intersect meshsets
01562     /** Intersect <em>meshset1</em> with <em>meshset2</em>, placing the results in meshset1.
01563         \param meshset1 Mesh set being intersected, also used to pass back result
01564         \param meshset2 Mesh set being intersected with <em>meshset1</em>
01565     */
01566     virtual ErrorCode intersect_meshset( EntityHandle meshset1, const EntityHandle meshset2 ) = 0;
01567 
01568     //! Unite meshsets
01569     /** Unite <em>meshset1</em> with <em>meshset2</em>, placing the results in meshset1.
01570         \param meshset1 Mesh set being united, also used to pass back result
01571         \param meshset2 Mesh set being united with <em>meshset1</em>
01572     */
01573     virtual ErrorCode unite_meshset( EntityHandle meshset1, const EntityHandle meshset2 ) = 0;
01574 
01575     //! Add to a meshset entities in specified range
01576     /** Add to a meshset entities in specified range.  If <em>meshset</em> has MESHSET_TRACK_OWNER
01577         option set, adjacencies are also added to entities in <em>entities</em>.
01578         \param meshset Mesh set being added to
01579         \param entities Range of entities being added to meshset
01580     */
01581     virtual ErrorCode add_entities( EntityHandle meshset, const Range& entities ) = 0;
01582 
01583     //! Add to a meshset entities in specified vector
01584     /** Add to a meshset entities in specified vector.  If <em>meshset</em> has MESHSET_TRACK_OWNER
01585         option set, adjacencies are also added to entities in <em>entities</em>.
01586         \param meshset Mesh set being added to
01587         \param entities 1d vector of entities being added to meshset
01588         \param num_entities Number of entities in 1d vector
01589     */
01590     virtual ErrorCode add_entities( EntityHandle meshset, const EntityHandle* entities, const int num_entities ) = 0;
01591 
01592     //! Remove from a meshset entities in specified range
01593     /** Remove from a meshset entities in specified range.  If <em>meshset</em> has
01594        MESHSET_TRACK_OWNER option set, adjacencies in entities in <em>entities</em> are updated.
01595         \param meshset Mesh set being removed from
01596         \param entities Range of entities being removed from meshset
01597     */
01598     virtual ErrorCode remove_entities( EntityHandle meshset, const Range& entities ) = 0;
01599 
01600     //! Remove from a meshset entities in specified vector
01601     /** Remove from a meshset entities in specified vector.  If <em>meshset</em> has
01602        MESHSET_TRACK_OWNER option set, adjacencies in entities in <em>entities</em> are updated.
01603         \param meshset Mesh set being removed from
01604         \param entities 1d vector of entities being removed from meshset
01605         \param num_entities Number of entities in 1d vector
01606     */
01607     virtual ErrorCode remove_entities( EntityHandle meshset, const EntityHandle* entities, const int num_entities ) = 0;
01608 
01609     //! Return whether a set contains entities
01610     /** Return whether a set contains entities.  Returns true only
01611      * if ALL entities are contained
01612      * \param meshset Mesh set being queried
01613      * \param entities Entities being queried
01614      * \param num_entities Number of entities
01615      * \return bool If true, all entities are contained in set
01616      */
01617     virtual bool contains_entities( EntityHandle meshset, const EntityHandle* entities, int num_entities,
01618                                     const int operation_type = Interface::INTERSECT ) = 0;
01619 
01620     //! Replace entities in a set with other entities
01621     /** Replace entities in a set with other entities
01622      *
01623      * \note  Behavior is undefined if an entity handle exists in both the
01624      *        old_entities and the new_entities arrays or old_entities
01625      *        contains multiple copies of an entity.
01626      * \note  If an entity occurs multiple times in an ordered set, all
01627      *        occurances will be replaced.
01628      * \note  For list-based sets, if not all handles in old_entities
01629      *        occcur in the set, the corresponding new_entities will not
01630      *        be added and  MB_ENTITY_NOT_FOUND will be returned.
01631      *        For set-based sets, all entities in new_entities wll be
01632      *        added and any contained entities in old_entities will be
01633      *        removed, and the return value will be MB_SUCCESS.
01634      * \param meshset Mesh set being modified
01635      * \param old_entities Entities to replace
01636      * \param new_entities New entities to add
01637      * \param num_entities Number of entities in input arrays
01638      * \return - MB_SUCCESS : all entities in old_entities replaced
01639      *         - MB_ENTITY_NOT_FOUND : one or more entities in new_entities
01640      *                        not added to set because corresponding entity
01641      *                        in old_entities did not occur in the ordered
01642      *                        set.
01643      *         - MB_FAILURE : internal error
01644      */
01645     virtual ErrorCode replace_entities( EntityHandle meshset, const EntityHandle* old_entities,
01646                                         const EntityHandle* new_entities, int num_entities ) = 0;
01647     /**@}*/
01648 
01649     /** \name Set parents/children */
01650 
01651     /**@{*/
01652 
01653     //! Get parent mesh sets of a mesh set
01654     /** If <em>num_hops</em> is 1, only immediate parents are returned.  If <em>num_hops</em> is
01655        zero, all ancenstors are returned.  Otherwise, <em>num_hops</em> specifies the maximum number
01656        of generations to traverse. \param meshset The mesh set whose parents are being queried
01657         \param parents STL vector holding the parents returned by this function
01658         \param num_hops Number of generations to traverse (0 = all)
01659     */
01660     virtual ErrorCode get_parent_meshsets( const EntityHandle meshset, std::vector< EntityHandle >& parents,
01661                                            const int num_hops = 1 ) const = 0;
01662 
01663     //! Get parent mesh sets of a mesh set
01664     /** If <em>num_hops</em> is 1, only immediate parents are returned.  If <em>num_hops</em> is
01665        zero, all ancenstors are returned.  Otherwise, <em>num_hops</em> specifies the maximum number
01666        of generations to traverse. \param meshset The mesh set whose parents are being queried
01667         \param parents Range holding the parents returned by this function
01668         \param num_hops Number of generations to traverse (0 = all)
01669     */
01670     virtual ErrorCode get_parent_meshsets( const EntityHandle meshset, Range& parents,
01671                                            const int num_hops = 1 ) const = 0;
01672 
01673     //! Get child mesh sets of a mesh set
01674     /** If <em>num_hops</em> is 1, only immediate children are returned.  If <em>num_hops</em> is
01675        zero, all ancenstors are returned.  Otherwise, <em>num_hops</em> specifies the maximum number
01676        of generations to traverse. \param meshset The mesh set whose children are being queried
01677         \param children STL vector holding the children returned by this function
01678         \param num_hops Number of generations to traverse (0 = all)
01679     */
01680     virtual ErrorCode get_child_meshsets( const EntityHandle meshset, std::vector< EntityHandle >& children,
01681                                           const int num_hops = 1 ) const = 0;
01682 
01683     //! Get child mesh sets of a mesh set
01684     /** If <em>num_hops</em> is 1, only immediate children are returned.  If <em>num_hops</em> is
01685        zero, all ancenstors are returned.  Otherwise, <em>num_hops</em> specifies the maximum number
01686        of generations to traverse. \param meshset The mesh set whose children are being queried
01687         \param children Range holding the children returned by this function
01688         \param num_hops Number of generations to traverse (0 = all)
01689     */
01690     virtual ErrorCode get_child_meshsets( const EntityHandle meshset, Range& children,
01691                                           const int num_hops = 1 ) const = 0;
01692 
01693     /**\brief Get mesh sets contained in a mesh set
01694      *
01695      * If <em>num_hops</em> is 1, only immediate contents are returned.
01696      * Otherwise a recursive query of all contained sets is performed,
01697      * returning every visted set.  The value of num_hops limites the
01698      * depth of the search, with zero indicating no depth limit.
01699      *
01700      *\param meshset The mesh set whose contents are being queried
01701      *\param contained The result list.
01702      *\param num_hops Number of generations to traverse (0 = all)
01703      */
01704     virtual ErrorCode get_contained_meshsets( const EntityHandle meshset, std::vector< EntityHandle >& contained,
01705                                               const int num_hops = 1 ) const = 0;
01706 
01707     /**\brief Get mesh sets contained in a mesh set
01708      *
01709      * If <em>num_hops</em> is 1, only immediate contents are returned.
01710      * Otherwise a recursive query of all contained sets is performed,
01711      * returning every visted set.  The value of num_hops limites the
01712      * depth of the search, with zero indicating no depth limit.
01713      *
01714      *\param meshset The mesh set whose contents are being queried
01715      *\param contained The result list.
01716      *\param num_hops Number of generations to traverse (0 = all)
01717      */
01718     virtual ErrorCode get_contained_meshsets( const EntityHandle meshset, Range& contained,
01719                                               const int num_hops = 1 ) const = 0;
01720 
01721     //! Get the number of parent mesh sets of a mesh set
01722     /** Identical to get_parent_meshsets, only number is returned instead of actual parents.
01723         \param meshset The mesh set whose parents are being queried
01724         \param number Number of parents
01725     */
01726     virtual ErrorCode num_parent_meshsets( const EntityHandle meshset, int* number, const int num_hops = 1 ) const = 0;
01727 
01728     //! Get the number of child mesh sets of a mesh set
01729     /** Identical to get_child_meshsets, only number is returned instead of actual children.
01730         \param meshset The mesh set whose children are being queried
01731         \param number Number of children
01732     */
01733     virtual ErrorCode num_child_meshsets( const EntityHandle meshset, int* number, const int num_hops = 1 ) const = 0;
01734 
01735     /**\brief Get the number of mesh sets contained in a mesh set
01736      *
01737      * Return the number of sets that would be returned by get_contained_meshsets
01738      *
01739      *\param meshset  The initial set to begin the query from.
01740      *\param number   (Output) The result count.
01741      *\param num_hops Search depth (0 => unbounded).
01742      */
01743     virtual ErrorCode num_contained_meshsets( const EntityHandle meshset, int* number,
01744                                               const int num_hops = 1 ) const = 0;
01745 
01746     //! Add a parent mesh set to a mesh set
01747     /** Make <em>parent_meshset</em> a new parent of <em>child_meshset</em>.  This function does
01748         <em>not</em> add a corresponding child link to <em>parent_meshset</em>.
01749         \param child_meshset The child mesh set being given a new parent.
01750         \param parent_meshset The parent being added to <em>child_meshset</em>
01751     */
01752     virtual ErrorCode add_parent_meshset( EntityHandle child_meshset, const EntityHandle parent_meshset ) = 0;
01753 
01754     //! Add a parent mesh sets to a mesh set
01755     /** Make <em>parent_meshset</em> a new parent of <em>child_meshset</em>.  This function does
01756         <em>not</em> add a corresponding child link to <em>parent_meshset</em>.
01757         \param child_meshset The child mesh set being given a new parent.
01758         \param parent_meshset The parent being added to <em>child_meshset</em>
01759     */
01760     virtual ErrorCode add_parent_meshsets( EntityHandle child_meshset, const EntityHandle* parent_meshsets,
01761                                            int num_parent_meshsets ) = 0;
01762 
01763     //! Add a child mesh set to a mesh set
01764     /** Make <em>child_meshset</em> a new child of <em>parent_meshset</em>.  This function does
01765         <em>not</em> add a corresponding parent link to <em>child_meshset</em>.
01766         \param parent_meshset The parent mesh set being given a new child.
01767         \param child_meshset The child being added to <em>parent_meshset</em>
01768     */
01769     virtual ErrorCode add_child_meshset( EntityHandle parent_meshset, const EntityHandle child_meshset ) = 0;
01770 
01771     //! Add a child mesh sets to a mesh set
01772     /** Make <em>child_meshset</em> a new child of <em>parent_meshset</em>.  This function does
01773         <em>not</em> add a corresponding parent link to <em>child_meshset</em>.
01774         \param parent_meshset The parent mesh set being given a new child.
01775         \param child_meshset The child being added to <em>parent_meshset</em>
01776     */
01777     virtual ErrorCode add_child_meshsets( EntityHandle parent_meshset, const EntityHandle* child_meshsets,
01778                                           int num_child_meshsets ) = 0;
01779 
01780     //! Add parent and child links between mesh sets
01781     /** Makes <em>child_meshset</em> a new child of <em>parent_meshset</em>, and vica versa.
01782         \param parent The parent mesh set being given a new child, and the new parent
01783         \param child The child being given a new parent, and the new child
01784     */
01785     virtual ErrorCode add_parent_child( EntityHandle parent, EntityHandle child ) = 0;
01786 
01787     //! Remove parent and child links between mesh sets
01788     /** Removes parent/child links between <em>child_meshset</em> and <em>parent_meshset</em>.
01789         \param parent The parent mesh set being removed from <em>child</em>
01790         \param child The child mesh set being removed from <em>parent</em>
01791     */
01792     virtual ErrorCode remove_parent_child( EntityHandle parent, EntityHandle child ) = 0;
01793 
01794     //! Remove a parent mesh set from a mesh set
01795     /** Removes <em>parent_meshset</em> from the parents of <em>child_meshset</em>.  This function
01796        does <em>not</em> remove a corresponding child link from <em>parent_meshset</em>. \param
01797        child_meshset The child mesh whose parent is being removed \param parent_meshset The parent
01798        being removed from <em>meshset</em>
01799     */
01800     virtual ErrorCode remove_parent_meshset( EntityHandle child_meshset, const EntityHandle parent_meshset ) = 0;
01801 
01802     //! Remove a child mesh set from a mesh set
01803     /** Removes <em>child_meshset</em> from the children of <em>parent_meshset</em>.  This function
01804        does <em>not</em> remove a corresponding parent link from <em>child_meshset</em>. \param
01805        parent_meshset The parent mesh set whose child is being removed \param child_meshset The
01806        child being removed from <em>parent_meshset</em>
01807     */
01808     virtual ErrorCode remove_child_meshset( EntityHandle parent_meshset, const EntityHandle child_meshset ) = 0;
01809 
01810     // ! Returns the global id tag; default value is -1
01811     virtual Tag globalId_tag() = 0;
01812 
01813     /**@}*/
01814 
01815     /** \name Set iterators */
01816 
01817     /**@{*/
01818 
01819     /** \brief Create an iterator over the set
01820      * Create a new iterator that iterates over entities with the specified type or dimension.
01821      * Only one of ent_type or dim can be set; use dim=-1 or ent_type=MBMAXTYPE for the other.
01822      * Iterators for list-type (ordered) sets are stable over set modification, unless entity
01823      * removed or deleted is the one at the current position of the iterator.  If the check_valid
01824      * parameter is passed as true, entities are checked for validity before being passed back by
01825      * get_next_entities function (checking entity validity can have a non-negligible cost).
01826      *
01827      * Iterators returned by this function can be deleted using the normal C++ delete function.
01828      * After creating the iterator through this function, further interactions are through methods
01829      * on the SetIterator class.
01830      * \param meshset The entity set associated with this iterator (use 0 for whole instance)
01831      * \param ent_type Entity type associated with this iterator
01832      * \param ent_dim Dimension associated with this iterator
01833      * \param chunk_size Chunk size of the iterator
01834      * \param check_valid If true, entities are checked for validity before being returned
01835      */
01836 
01837     virtual ErrorCode create_set_iterator( EntityHandle meshset, EntityType ent_type, int ent_dim, int chunk_size,
01838                                            bool check_valid, SetIterator*& set_iter ) = 0;
01839     /**@}*/
01840 
01841     // ************************  Interface options controllable by user  ***************
01842 
01843     /** \name Sequence Option controllers */
01844 
01845     /**@{*/
01846 
01847     /** \brief Interface to control memory allocation for sequences
01848      * Provide a factor that controls the size of the sequence that gets allocated.
01849      * This is typically useful in the parallel setting when a-priori, the number of ghost entities
01850      * and the memory required for them within the same sequence as the owned entities are unknown.
01851      * The default factor is 1.0 but this can be appropriately updated at runtime so that we do not
01852      * have broken sequences.
01853      */
01854     virtual double get_sequence_multiplier() const = 0;
01855 
01856     /** \brief Interface to control memory allocation for sequences
01857      * Provide a factor that controls the size of the sequence that gets allocated.
01858      * This is typically useful in the parallel setting when a-priori, the number of ghost entities
01859      * and the memory required for them within the same sequence as the owned entities are unknown.
01860      * The default factor is 1.0 but this can be appropriately updated at runtime so that we do not
01861      * have broken sequences.
01862      *
01863      * \param meshset User specified multiplier (should be greater than 1.0)
01864      */
01865     virtual void set_sequence_multiplier( double factor ) = 0;
01866 
01867     /**@}*/
01868 };
01869 
01870 //! predicate for STL algorithms.  Returns true if the entity handle is
01871 //! of the specified type.  For example, to remove all the tris out of a list
01872 //! of 2D entities retrieved using get_adjacencies you could do
01873 //! std::remove_if(list.begin(), list.end(), type_equals(gMB, MBTRI));
01874 class type_equals : public std::unary_function< EntityHandle, bool >
01875 {
01876   public:
01877     //! interface object
01878     Interface* meshDB;
01879 
01880     //! type corresponding to this predicate
01881     const EntityType test_type;
01882 
01883     //! Constructor
01884     type_equals( Interface* mdb, const EntityType type ) : meshDB( mdb ), test_type( type ) {}
01885 
01886     //! operator predicate
01887     bool operator()( EntityHandle handle ) const
01888     {
01889         return ( meshDB->type_from_handle( handle ) == test_type );
01890     }
01891 };
01892 
01893 //! predicate for STL algorithms.  Returns true if the entity handle is not
01894 //! of the specified type.  For example, to remove all but the tris out of a list
01895 //! of 2D entities retrieved using get_adjacencies you could do
01896 //! std::remove_if(list.begin(), list.end(), type_not_equals(gMB, MBTRI));
01897 class type_not_equals : public std::unary_function< EntityHandle, bool >
01898 {
01899   public:
01900     //! interface object
01901     Interface* meshDB;
01902 
01903     //! type corresponding to this predicate
01904     const EntityType test_type;
01905 
01906     //! Constructor
01907     type_not_equals( Interface* mdb, const EntityType type ) : meshDB( mdb ), test_type( type ) {}
01908 
01909     //! operator predicate
01910     bool operator()( EntityHandle handle ) const
01911     {
01912         return ( meshDB->type_from_handle( handle ) != test_type );
01913     }
01914 };
01915 
01916 inline float Interface::api_version( std::string* version_string )
01917 {
01918     if( NULL != version_string )
01919         *version_string = std::string( "MOAB API version " ) + std::string( MOAB_API_VERSION_STRING );
01920     return MOAB_API_VERSION;
01921 }
01922 
01923 }  // namespace moab
01924 
01925 #endif  // MB_INTERFACE_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines