Mesh Oriented datABase  (version 5.6.0)
An array-based unstructured mesh library
Interface.hpp
Go to the documentation of this file.
1 /** \mainpage The Mesh-Oriented datABase (MOAB)
2  *
3  * MOAB is a component for representing and evaluating mesh data. MOAB can store
4  * structured and unstructured mesh, consisting of elements in the finite element "zoo",
5  * along with polygons and polyhedra. The functional interface to MOAB is simple, consisting
6  * of only four fundamental data types. This data is quite powerful, allowing the representation
7  * of most types of metadata commonly found on the mesh. MOAB is optimized for efficiency in
8  * space and time, based on access to mesh in chunks rather than through individual entities,
9  * while also versatile enough to support individual entity access.
10  *
11  * The MOAB data model consists of the following four fundamental types: mesh interface instance,
12  * mesh entities (vertex, edge, tri, etc.), sets, and tags. Entities are addressed through handles
13  * rather than pointers, to allow the underlying representation of an entity to change without
14  * changing the handle to that entity. Sets are arbitrary groupings of mesh entities and other
15  * sets. Sets also support parent/child relationships as a relation distinct from sets containing
16  * other sets. The directed-graph provided by set parent/child relationships is useful for modeling
17  * topological relations from a geometric model and other metadata. Tags are named data which can
18  * be assigned to the mesh as a whole, individual entities, or sets. Tags are a mechanism for
19  * attaching data to individual entities and sets are a mechanism for describing relations between
20  * entities; the combination of these two mechanisms is a powerful yet simple interface for
21  * representing metadata or application-specific data. For example, sets and tags can be used
22  * together to describe geometric topology, boundary condition, and inter-processor interface
23  * groupings in a mesh.
24  *
25  * MOAB's API is documented in the moab::Interface class. Questions and comments should be sent to
26  * moab-dev _at_ mcs.anl.gov.
27  *
28  * \ref userguide "User's Guide"
29  *
30  * \ref developerguide "Developer's Guide"
31  *
32  * \ref metadata "I/O and Meta-Data Storage Conventions in MOAB"
33  *
34  * <a href="pages.html">Full List of Documents</a>
35  */
36 
37 #ifndef MOAB_INTERFACE_HPP
38 #define MOAB_INTERFACE_HPP
39 
40 #include "win32_config.h"
41 
42 #define MOAB_API_VERSION 1.01
43 #define MOAB_API_VERSION_STRING "1.01"
44 
45 #include "moab/MOABConfig.h"
46 #include "moab/Forward.hpp"
47 #include "moab/Range.hpp"
48 #include "moab/Compiler.hpp"
49 #include "moab/ErrorHandler.hpp"
50 
51 // include files
52 #include <string>
53 #include <functional>
54 #include <typeinfo>
55 
56 //! component architecture definitions
57 #ifdef XPCOM_MB
58 
59 #ifndef __gen_nsISupports_h__
60 #include "nsISupports.h"
61 #endif
62 
63 #ifndef NS_NO_VTABLE
64 #define NS_NO_VTABLE
65 #endif
66 
67 #define MBINTERFACE_IID_STR "f728830e-1dd1-11b2-9598-fb9f414f2465"
68 
69 #define MBINTERFACE_IID { 0xf728830e, 0x1dd1, 0x11b2, { 0x95, 0x98, 0xfb, 0x9f, 0x41, 0x4f, 0x24, 0x65 } }
70 
71 #endif
72 
73 #include "moab/UnknownInterface.hpp"
74 #define MB_INTERFACE_VERSION "2.0.0"
75 namespace moab
76 {
77 
78 static const MBuuid IDD_MBCore = MBuuid( 0x8956e0a, 0xc300, 0x4005, 0xbd, 0xf6, 0xc3, 0x4e, 0xf7, 0x1f, 0x5a, 0x52 );
79 
80 /**
81  * \class Interface Interface.hpp "moab/Interface.hpp"
82  * \brief Main interface class to MOAB
83  * \nosubgrouping
84  */
85 #if defined( XPCOM_MB )
86 class NS_NO_VTABLE Interface : public nsISupports
87 {
88 #else
89 class MOAB_EXPORT Interface : public UnknownInterface
90 {
91 #endif
92 
93  public:
94 #ifdef XPCOM_MB
95  NS_DEFINE_STATIC_IID_ACCESSOR( MBINTERFACE_IID )
96 #endif
97 
98  /** \name Interface */
99 
100  /**@{*/
101 
102  //! constructor
103  Interface() {}
104 
105  //! destructor
106  virtual ~Interface() {}
107 
108  //! return the entity set representing the whole mesh
109  virtual EntityHandle get_root_set() = 0;
110 
111  //! Get a pointer to an internal MOAB interface
112  //!\return NULL if not found, iterface pointer otherwise
113  virtual ErrorCode query_interface_type( const std::type_info& iface_type, void*& iface ) = 0;
114 
115  //! Get a pointer to an internal MOAB interface
116  //!\return NULL if not found, iterface pointer otherwise
117  template < class IFace >
118  ErrorCode query_interface( IFace*& ptr )
119  {
120  void* tmp_ptr;
121  ErrorCode result = query_interface_type( typeid( IFace ), tmp_ptr );
122  ptr = reinterpret_cast< IFace* >( tmp_ptr );
123  return result;
124  }
125 
126  //! Release reference to MB interface
127  virtual ErrorCode release_interface_type( const std::type_info& iface_type, void* iface ) = 0;
128 
129  template < class IFace >
130  ErrorCode release_interface( IFace* interface )
131  {
132  return release_interface_type( typeid( IFace ), interface );
133  }
134 
135  //! Release reference to MB interface
136 
137  //! Returns the major.minor version number of the interface
138  /**
139  \param version_string If non-NULL, will be filled in with a string, possibly
140  containing implementation-specific information
141  */
142  virtual float api_version( std::string* version_string = NULL );
143 
144  //! Returns the major.minor version number of the implementation
145  /**
146  \param version_string If non-NULL, will be filled in with a string, possibly
147  containing implementation-specific information
148  */
149  virtual float impl_version( std::string* version_string = NULL ) = 0;
150 
151  /**@}*/
152 
153  /** \name Type and id */
154 
155  /**@{*/
156 
157  //! Returns the entity type of an EntityHandle.
158  /** Returns the EntityType (ie, MBVERTEX, MBQUAD, MBHEX ) of <em>handle</em>.
159  \param handle The EntityHandle you want to find the entity type of.
160  \return type The entity type of <em>handle</em>.
161 
162  Example: \code
163  EntityType type = type_from_handle( handle);
164  if( type == MBHEX ) ... \endcode
165  */
166  virtual EntityType type_from_handle( const EntityHandle handle ) const = 0;
167 
168  //! Returns the id from an EntityHandle.
169  /** \param handle The EntityHandle you want to find the id of.
170  \return id Id of <em>handle</em>
171 
172  Example: \code
173  int id = id_from_handle(handle); \endcode
174  */
175  virtual EntityID id_from_handle( const EntityHandle handle ) const = 0;
176 
177  //! Returns the topological dimension of an entity
178  /** Returns the topological dimension of an entity.
179  \param handle The EntityHandle you want to find the dimension of.
180  \return type The topological dimension of <em>handle</em>.
181 
182  Example: \code
183  int dim = dimension_from_handle( handle);
184  if( dim == 0 ) ... \endcode
185  */
186  virtual int dimension_from_handle( const EntityHandle handle ) const = 0;
187 
188  //! Gets an entity handle from the data base, if it exists, according to type and id.
189  /** Given an EntiyType and an id, this function gets the existent EntityHandle.
190  If no such EntityHandle exits, it returns MB_ENTITY_NOT_FOUND
191  and sets handle to zero.
192  \param type The type of the EntityHandle to retrieve from the database.
193  \param id The id of the EntityHandle to retrieve from the database.
194  \param handle An EntityHandle of type <em>type</em> and <em>id</em>.
195 
196  Example: \code
197  EntityType handle;
198  ErrorCode error_code = handle_from_id(MBTRI, 204, handle );
199  if( error_code == MB_ENTITY_NOT_FOUND ) ... \endcode
200  */
201  virtual ErrorCode handle_from_id( const EntityType type, const EntityID, EntityHandle& handle ) const = 0;
202 
203  /**@}*/
204 
205  /** \name Mesh input/output */
206 
207  /**@{*/
208 
209  //! Loads a mesh file into the database.
210  /** Loads the file 'file_name'; types of mesh which can be loaded
211  depend on modules available at MB compile time. If
212  active_block_id_list is NULL, all material sets (blocks in the
213  ExodusII jargon) are loaded. Individual material sets can be
214  loaded by specifying their ids in 'active_block_id_list'. All
215  nodes are loaded on first call for a given file. Subsequent
216  calls for a file load any material sets not loaded in previous
217  calls.
218  \param file_name Name of file to load into database.
219  \param active_block_id_list Material set/block ids to load.
220  If NULL, ALL blocks of <em>file_name</em> are loaded.
221  \param num_blocks Number of blocks in active_block_id_list
222 
223  Example: \code
224  std::vector<int> active_block_id_list;
225  int active_block_id_list[] = {1, 4, 10};
226  load_mesh( "temp.gen", active_block_id_list, 3 ); //load blocks 1, 4, 10
227  \endcode
228  */
229  virtual ErrorCode load_mesh( const char* file_name,
230  const int* active_block_id_list = NULL,
231  const int num_blocks = 0 ) = 0;
232 
233  /**\brief Load or import a file.
234  *
235  * Load a MOAB-native file or import data from some other supported
236  * file format.
237  *
238  *\param file_name The location of the file to read.
239  *\param file_set If non-null, this argument must be a pointer to
240  * a valid entity set handle. All entities read from
241  * the file will be added to this set. File metadata
242  * will be added to tags on the set.
243  *\param options A list of string options, separated by semicolons (;).
244  * See README.IO for more information. Options are typically
245  * format-specific options or parallel options. If an
246  * option value is unrecognized but the file read otherwise
247  * succeeded, MB_UNHANDLED_OPTION will be returned.
248  *\param set_tag_name The name of a tag used to designate the subset
249  * of the file to read. The name must correspond to
250  * data in the file that will be instantiated in MOAB
251  * as a tag.
252  *\param set_tag_values If the name specified in 'set_tag_name'
253  * corresponds to a tag with a single integer value,
254  * the values in this tag can be used to further
255  * limit the subset of data written from the file to
256  * only those entities or sets that have a value for
257  * the tag that is one of the values in this array.
258  *\param num_set_tag_values The length of set_tag_values.
259  *
260  *\note file_set is passed by pointer rather than by value (where a
261  * zero handle value would indicate no set) so as to intentionally
262  * break compatibility with the previous version of this function
263  * because the behavior with respect to the file set was changed.
264  * The file_set is now an input-only argument. The previous
265  * version of this function unconditionally created a set and
266  * passed it back to the caller via a non-const reference argument.
267  */
268  virtual ErrorCode load_file( const char* file_name,
269  const EntityHandle* file_set = 0,
270  const char* options = 0,
271  const char* set_tag_name = 0,
272  const int* set_tag_values = 0,
273  int num_set_tag_values = 0 ) = 0;
274 
275  //! Writes mesh to a file.
276  /** Write mesh to file 'file_name'; if output_list is non-NULL, only
277  material sets contained in that list will be written.
278  \param file_name Name of file to write.
279  \param output_list 1d array of material set handles to write; if
280  NULL, all sets are written
281  \param num_sets Number of sets in output_list array
282 
283  Example: \code
284  EntityHandle output_list[] = {meshset1, meshset2, meshset3};
285  write_mesh( "output_file.gen", output_list, 3 ); \endcode
286  */
287  virtual ErrorCode write_mesh( const char* file_name,
288  const EntityHandle* output_list = NULL,
289  const int num_sets = 0 ) = 0;
290 
291  /**\brief Write or export a file.
292  *
293  * Write a MOAB-native file or export data to some other supported
294  * file format.
295  *
296  *\param file_name The location of the file to write.
297  *\param file_type The type of the file. If this value is NULL,
298  * then file type will be determined using the
299  * file name suffix.
300  *\param options A semicolon-separated list of options.
301  * See README.IO for more information. Typical options
302  * include the file type, parallel options, and options
303  * specific to certain file formats.
304  *\param output_sets A list of entity sets to write to the file. If
305  * no sets are sepcified, the default behavior is to
306  * write all data that is supported by the target file
307  * type.
308  *\param num_output_sets The length of the output_sets array.
309  *\param tag_list A list of tags for which to write the tag data. The
310  * write may fail if a tag list is specified but the
311  * target file type is not capable of representing the
312  * data. If no tags are specified, the default is to
313  * write whatever data the target file format supports.
314  *\param num_tags The length of tag_list.
315  */
316  virtual ErrorCode write_file( const char* file_name,
317  const char* file_type = 0,
318  const char* options = 0,
319  const EntityHandle* output_sets = 0,
320  int num_output_sets = 0,
321  const Tag* tag_list = 0,
322  int num_tags = 0 ) = 0;
323 
324  /**\brief Write or export a file.
325  *
326  * Write a MOAB-native file or export data to some other supported
327  * file format.
328  *
329  *\param file_name The location of the file to write.
330  *\param file_type The type of the file. If this value is NULL,
331  * then file type will be determined using the
332  * file name suffix.
333  *\param options A semicolon-separated list of options.
334  * See README.IO for more information. Typical options
335  * include the file type, parallel options, and options
336  * specific to certain file formats.
337  *\param output_sets A list of entity sets to write to the file. If
338  * no sets are sepcified, the default behavior is to
339  * write all data that is supported by the target file
340  * type.
341  *\param tag_list A list of tags for which to write the tag data. The
342  * write may fail if a tag list is specified but the
343  * target file type is not capable of representing the
344  * data. If no tags are specified, the default is to
345  * write whatever data the target file format supports.
346  *\param num_tags The length of tag_list.
347  */
348  virtual ErrorCode write_file( const char* file_name,
349  const char* file_type,
350  const char* options,
351  const Range& output_sets,
352  const Tag* tag_list = 0,
353  int num_tags = 0 ) = 0;
354 
355  //! Deletes all mesh entities from this MB instance
356  virtual ErrorCode delete_mesh() = 0;
357 
358  /**@}*/
359 
360  /** \name Coordinates and dimensions */
361 
362  /**@{*/
363 
364  //! Get blocked vertex coordinates for all vertices
365  /** Blocked = all x, then all y, etc.
366 
367  Example: \code
368  std::vector<double> coords;
369  get_vertex_coordinates(coords);
370  double xavg = 0;
371  for (int i = 0; i < coords.size()/3; i++) xavg += coords[i]; \endcode
372  */
373  virtual ErrorCode get_vertex_coordinates( std::vector< double >& coords ) const = 0;
374 
375  //! get pointers to coordinate data
376  /** BEWARE, THIS GIVES ACCESS TO MOAB'S INTERNAL STORAGE, USE WITH CAUTION!
377  * This function returns pointers to MOAB's internal storage for vertex coordinates.
378  * Access is similar to tag_iterate, see documentation for that function for details
379  * about arguments and a coding example.
380  */
381  virtual ErrorCode coords_iterate( Range::const_iterator iter,
382  /**< Iterator to first entity you want coordinates for */
383  Range::const_iterator end,
384  /**< Iterator to last entity you want coordinates for */
385  double*& xcoords_ptr,
386  /**< Pointer to x coordinate storage for these entities */
387  double*& ycoords_ptr,
388  /**< Pointer to y coordinate storage for these entities */
389  double*& zcoords_ptr,
390  /**< Pointer to z coordinate storage for these entities */
391  int& count
392  /**< Number of entities for which returned pointers are valid/contiguous */
393  ) = 0;
394 
395  //! Gets xyz coordinate information for range of vertices
396  /** Length of 'coords' should be at least 3*<em>entity_handles.size()</em> before making call.
397  \param entity_handles Range of vertex handles (error if not of type MBVERTEX)
398  \param coords Array used to return x, y, and z coordinates.
399 
400  Example: \code
401  double coords[3];
402  get_coords( vertex_handle, coords );
403  std::cout<<"x = "<<coords[0]<<std::endl;
404  std::cout<<"y = "<<coords[1]<<std::endl;
405  std::cout<<"z = "<<coords[2]<<std::endl; \endcode
406  */
407  virtual ErrorCode get_coords( const Range& entity_handles, double* coords ) const = 0;
408 
409  //! Gets xyz coordinate information for vector of vertices
410  /** Identical to range-based function, except entity handles are specified using a 1d vector
411  and vector length.
412  */
413  virtual ErrorCode get_coords( const EntityHandle* entity_handles,
414  const int num_entities,
415  double* coords ) const = 0;
416 
417  /**\brief Get vertex coordinates in blocks by dimension.
418  *
419  * Get the X, Y, and Z coordinates of a group of vertices.
420  * Coordinates are returned in separate arrays, one for each
421  * dimension. Each coordinate array must be of sufficient
422  * length to hold the coordinate value for each vertex. Array
423  * pointers may be NULL if coordinates in the the respective
424  * dimension are not desired.
425  *\param entity_handles The group of vertex handles for which to get the coordiantes.
426  *\param x_coords Output: the X coordinate of each vertex. May be NULL.
427  *\param y_coords Output: the Y coordinate of each vertex. May be NULL.
428  *\param z_coords Output: the Z coordinate of each vertex. May be NULL.
429  */
430  virtual ErrorCode get_coords( const Range& entity_handles,
431  double* x_coords,
432  double* y_coords,
433  double* z_coords ) const = 0;
434 
435  //! Sets the xyz coordinates for a vector of vertices
436  /** An error is returned if any entities in the vector are not vertices.
437  \param entity_handles EntityHandle's to set coordinates of. (Must be of type MBVERTEX)
438  \param num_entities Number of entities in entity_handles
439  \param coords Array containing new xyz coordinates.
440 
441  Example: \code
442  double coords[3] = {0.234, -2.52, 12.023};
443  set_coords( entity_handle, 1, coords ); \endcode
444  */
445  virtual ErrorCode set_coords( const EntityHandle* entity_handles,
446  const int num_entities,
447  const double* coords ) = 0;
448 
449  //! Sets the xyz coordinates for a vector of vertices
450  /** An error is returned if any entities in the vector are not vertices.
451  \param entity_handles EntityHandle's to set coordinates of. (Must be of type MBVERTEX)
452  \param num_entities Number of entities in entity_handles
453  \param coords Array containing new xyz coordinates.
454 
455  Example: \code
456  double coords[3] = {0.234, -2.52, 12.023};
457  set_coords( entity_handle, 1, coords ); \endcode
458  */
459  virtual ErrorCode set_coords( Range entity_handles, const double* coords ) = 0;
460 
461  //! Get overall geometric dimension
462  virtual ErrorCode get_dimension( int& dim ) const = 0;
463 
464  //! Set overall geometric dimension
465  /** Returns error if setting to 3 dimensions, mesh has been created, and
466  * there are only 2 dimensions on that mesh
467  */
468  virtual ErrorCode set_dimension( const int dim ) = 0;
469 
470  /**@}*/
471 
472  /** \name Connectivity */
473 
474  /**@{*/
475 
476  //! get pointers to connectivity data
477  /** BEWARE, THIS GIVES ACCESS TO MOAB'S INTERNAL STORAGE, USE WITH CAUTION!
478  * This function returns a pointer to MOAB's internal storage for entity connectivity.
479  * For each contiguous sub-range of entities, those entities are guaranteed to have
480  * the same number of vertices (since they're in the same ElementSequence). Count
481  * is given in terms of entities, not elements of the connectivity array.
482  * Access is similar to tag_iterate, see documentation for that function for details
483  * about arguments and a coding example.
484  */
485  virtual ErrorCode connect_iterate( Range::const_iterator iter,
486  /**< Iterator to first entity you want coordinates for */
487  Range::const_iterator end,
488  /**< Iterator to last entity you want coordinates for */
489  EntityHandle*& connect,
490  /**< Pointer to connectivity storage for these entities */
491  int& verts_per_entity,
492  /**< Number of vertices per entity in this block of entities */
493  int& count
494  /**< Number of entities for which returned pointers are valid/contiguous */
495  ) = 0;
496 
497  //! Get the connectivity array for all entities of the specified entity type
498  /** This function returns the connectivity of just the corner vertices, no higher order nodes
499  \param type The entity type of elements whose connectivity is to be returned
500  \param connect an STL vector used to return connectivity array (in the form of entity
501  handles)
502  */
503  virtual ErrorCode get_connectivity_by_type( const EntityType type, std::vector< EntityHandle >& connect ) const = 0;
504 
505  //! Gets the connectivity for a vector of elements
506  /** Same as vector-based version except range is returned (unordered!)
507  */
508  virtual ErrorCode get_connectivity( const EntityHandle* entity_handles,
509  const int num_handles,
510  Range& connectivity,
511  bool corners_only = false ) const = 0;
512 
513  //! Gets the connectivity for elements
514  /** Same as vector-based version except range is returned (unordered!)
515  */
516  virtual ErrorCode get_connectivity( const Range& entity_handles,
517  Range& connectivity,
518  bool corners_only = false ) const = 0;
519 
520  //! Gets the connectivity for a vector of elements
521  /** Corner vertices or all vertices (including higher-order nodes, if any) are returned.
522  For non-element handles (ie, MB_MeshSets), returns an error. Connectivity data is copied
523  from the database into the vector. Connectivity of a vertex is the same vertex.
524  The nodes in <em>connectivity</em> are properly ordered according to that element's
525  canonical ordering.
526  \param entity_handles Vector of element handles to get connectivity of.
527  \param num_handles Number of entity handles in <em>entity_handles</em>
528  \param connectivity Vector in which connectivity of <em>entity_handles</em> is returned.
529  \param corners_only If true, returns only corner vertices, otherwise returns all of them
530  (including any higher-order vertices) \param offsets If non-NULL, offsets->[i] stores the
531  index of the start of entity i's connectivity, with the last value in offsets one beyond the
532  last entry
533  */
534  virtual ErrorCode get_connectivity( const EntityHandle* entity_handles,
535  const int num_handles,
536  std::vector< EntityHandle >& connectivity,
537  bool corners_only = false,
538  std::vector< int >* offsets = NULL ) const = 0;
539 
540  //! Gets a pointer to constant connectivity data of <em>entity_handle</em>
541  /** Sets <em>number_nodes</em> equal to the number of nodes of the <em>
542  entity_handle </em>. Faster then the other <em>get_connectivity</em> function because no
543  data is copied. The nodes in 'connectivity' are properly ordered according to the
544  element's canonical ordering.
545 
546 
547  Example: \code
548  const EntityHandle* conn;
549  int number_nodes = 0;
550  get_connectivity( entity_handle, conn, number_nodes ); \endcode
551 
552  Example2: \code
553  std::vector<EntityHandle> sm_storage;
554  const EntityHandle* conn;
555  int number_nodes;
556  get_connectivity( handle, conn, number_nodes, false, &sm_storage );
557  if (conn == &sm_storage[0])
558  std::cout << "Structured mesh element" << std::endl;
559  \endcode
560 
561  \param entity_handle EntityHandle to get connectivity of.
562  \param connectivity Array in which connectivity of <em>entity_handle</em> is returned.
563  \param num_nodes Number of MeshVertices in array <em>connectivity</em>.
564  \param corners_only If true, returns only corner vertices, otherwise returns all of them
565  (including any higher-order vertices) \param storage Some elements (e.g. structured mesh) may
566  not have an explicit connectivity list. This function will normally return
567  MB_NOT_IMPLEMENTED for such elements. However, if the caller passes in a non-null value for
568  this argument, space will be allocated in this vector for the connectivity data and the
569  connectivity pointer will be set to the data in this vector.
570  */
571  virtual ErrorCode get_connectivity( const EntityHandle entity_handle,
572  const EntityHandle*& connectivity,
573  int& num_nodes,
574  bool corners_only = false,
575  std::vector< EntityHandle >* storage = 0 ) const = 0;
576 
577  //! Sets the connectivity for an EntityHandle. For non-element handles, return an error.
578  /** Connectivity is stored exactly as it is ordered in vector <em>connectivity</em>.
579  \param entity_handle EntityHandle to set connectivity of.
580  \param connect Vector containing new connectivity of <em>entity_handle</em>.
581  \param num_connect Number of vertices in <em>connect</em>
582 
583  Example: \code
584  EntityHandle conn[] = {node1, node2, node3};
585  set_connectivity( tri_element, conn, 3 ); \endcode
586  */
587  virtual ErrorCode set_connectivity( const EntityHandle entity_handle,
588  EntityHandle* connect,
589  const int num_connect ) = 0;
590 
591  /**@}*/
592 
593  /** \name Adjacencies */
594 
595  /**@{*/
596 
597  //! Get the adjacencies associated with a vector of entities to entities of a specfied
598  //! dimension.
599  /** \param from_entities Vector of EntityHandle to get adjacencies of.
600  \param num_entities Number of entities in <em>from_entities</em>
601  \param to_dimension Dimension of desired adjacencies
602  \param create_if_missing If true, MB will create any entities of the specfied dimension
603  which have not yet been created (only useful when <em>to_dimension <
604  dim(*from_entities)</em>) \param adj_entities STL vector to which adjacent entities are
605  appended. \param operation_type Enum of INTERSECT or UNION. Defines whether to take the
606  intersection or union of the set of adjacencies recovered for the from_entities.
607 
608  The adjacent entities in vector <em>adjacencies</em> are not in any particular
609  order.
610 
611  Example: \code
612  std::vector<EntityHandle> adjacencies, from_entities = {hex1, hex2};
613  // generate all edges for these two hexes
614  get_adjacencies( from_entities, 2, 1, true, adjacencies, Interface::UNION);
615  adjacencies.clear();
616  // now find the edges common to both hexes
617  get_adjacencies( from_entities, 2, 1, false, adjacencies, Interface::INTERSECT);
618  \endcode
619  */
620 
621  virtual ErrorCode get_adjacencies( const EntityHandle* from_entities,
622  const int num_entities,
623  const int to_dimension,
624  const bool create_if_missing,
625  std::vector< EntityHandle >& adj_entities,
626  const int operation_type = Interface::INTERSECT ) = 0;
627 
628  //! Get the adjacencies associated with a vector of entities to entities of a specfied
629  //! dimension.
630  /** Identical to vector-based get_adjacencies function, except results are returned in a
631  range instead of a vector.
632  */
633  virtual ErrorCode get_adjacencies( const EntityHandle* from_entities,
634  const int num_entities,
635  const int to_dimension,
636  const bool create_if_missing,
637  Range& adj_entities,
638  const int operation_type = Interface::INTERSECT ) = 0;
639 
640  //! Get the adjacencies associated with a range of entities to entities of a specfied dimension.
641  /** Identical to vector-based get_adjacencies function, except "from" entities specified in a
642  range instead of a vector.
643  */
644  virtual ErrorCode get_adjacencies( const Range& from_entities,
645  const int to_dimension,
646  const bool create_if_missing,
647  Range& adj_entities,
648  const int operation_type = Interface::INTERSECT ) = 0;
649 
650  //! Adds adjacencies between "from" and "to" entities.
651  /** \param from_handle Entities on which the adjacencies are placed
652  \param to_handles Vector of entities referenced by new adjacencies added to
653  <em>from_handle</em> \param num_handles Number of entities in <em>to_handles</em> \param
654  both_ways If true, add the adjacency information in both directions; if false, adjacencies
655  are added only to <em>from_handle</em>
656  */
657  virtual ErrorCode add_adjacencies( const EntityHandle from_handle,
658  const EntityHandle* to_handles,
659  const int num_handles,
660  bool both_ways ) = 0;
661 
662  //! Adds adjacencies; same as vector-based, but with range instead
663  virtual ErrorCode add_adjacencies( const EntityHandle from_handle, Range& adjacencies, bool both_ways ) = 0;
664 
665  //! Removes adjacencies between handles.
666  /** Adjacencies in both directions are removed.
667  \param from_handle Entity from which adjacencies are being removed.
668  \param to_handles Entities to which adjacencies are being removed.
669  \param num_handles Number of handles in <em>to_handles</em>
670  */
671  virtual ErrorCode remove_adjacencies( const EntityHandle from_handle,
672  const EntityHandle* to_handles,
673  const int num_handles ) = 0;
674 
675  /**\brief Get a ptr to adjacency lists
676  * Get a pointer to adjacency lists. These lists are std::vector<EntityHandle>, which are
677  * pointed to by adjs[i]. Adjacencies are not guaranteed to be in order of increasing
678  * dimension. Only a const version of this function is given, because adjacency data is managed
679  * more carefully in MOAB and should be treated as read-only by applications. If adjacencies
680  * have not yet been initialized, adjs_ptr will be NULL (i.e. adjs_ptr == NULL). There may also
681  * be NULL entries for individual entities, i.e. adjs_ptr[i] == NULL. \param iter Iterator to
682  * beginning of entity range desired \param end End iterator for which adjacencies are requested
683  * \param adjs_ptr Pointer to pointer to const std::vector<EntityHandle>; each member of that
684  * array is the vector of adjacencies for this entity \param count Number of entities in the
685  * contiguous chunk starting from *iter
686  */
687  virtual ErrorCode adjacencies_iterate( Range::const_iterator iter,
688  Range::const_iterator end,
689  const std::vector< EntityHandle >**& adjs_ptr,
690  int& count ) = 0;
691  /**@}*/
692 
693  //! Enumerated type used in get_adjacencies() and other functions
694  enum
695  {
696  INTERSECT,
697  UNION
698  };
699 
700  /** \name Getting entities */
701 
702  /**@{*/
703 
704  //! Retrieves all entities of a given topological dimension in the database or meshset.
705  /** Appends entities to list passed in.
706  \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
707  \param dimension Topological dimension of entities desired.
708  \param entities Range in which entities of dimension <em>dimension</em> are returned.
709  \param recursive If true, meshsets containing meshsets are queried recursively. Returns
710  the contents of meshsets, but not the meshsets themselves if true.
711 
712  Example: \code
713  // get 1d (edge) elements in the entire mesh
714  Range edges;
715  get_entities_by_dimension( 0, 1, edges );
716  \endcode
717  */
718  virtual ErrorCode get_entities_by_dimension( const EntityHandle meshset,
719  const int dimension,
720  Range& entities,
721  const bool recursive = false ) const = 0;
722 
723  //! Retrieves all entities of a given topological dimension in the database or meshset.
724  /** Appends entities to list passed in.
725  \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
726  \param dimension Topological dimension of entities desired.
727  \param entities Range in which entities of dimension <em>dimension</em> are returned.
728  \param recursive If true, meshsets containing meshsets are queried recursively. Returns
729  the contents of meshsets, but not the meshsets themselves if true.
730 
731  Example: \code
732  // get 1d (edge) elements in the entire mesh
733  Range edges;
734  get_entities_by_dimension( 0, 1, edges );
735  \endcode
736  */
737  virtual ErrorCode get_entities_by_dimension( const EntityHandle meshset,
738  const int dimension,
739  std::vector< EntityHandle >& entities,
740  const bool recursive = false ) const = 0;
741 
742  //! Retrieve all entities of a given type in the database or meshset.
743  /** Appends entities to list passed in.
744  \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
745  \param type Type of entities to be returned
746  \param entities Range in which entities of type <em>type</em> are returned.
747  \param recursive If true, meshsets containing meshsets are queried recursively. Returns
748  the contents of meshsets, but not the meshsets themselves. Specifying
749  both recursive=true and type=MBENTITYSET is an error, as it would always
750  result in an empty list.
751 
752  Example: \code
753  // get the quadrilateral elements in meshset
754  Range quads;
755  get_entities_by_type( meshset, MBQUAD, quads );
756  \endcode
757  */
758  virtual ErrorCode get_entities_by_type( const EntityHandle meshset,
759  const EntityType type,
760  Range& entities,
761  const bool recursive = false ) const = 0;
762 
763  //! Retrieve all entities of a given type in the database or meshset.
764  /** Appends entities to list passed in.
765  \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
766  \param type Type of entities to be returned
767  \param entities Range in which entities of type <em>type</em> are returned.
768  \param recursive If true, meshsets containing meshsets are queried recursively. Returns
769  the contents of meshsets, but not the meshsets themselves. Specifying
770  both recursive=true and type=MBENTITYSET is an error, as it would always
771  result in an empty list.
772 
773  Example: \code
774  // get the quadrilateral elements in meshset
775  Range quads;
776  get_entities_by_type( meshset, MBQUAD, quads );
777  \endcode
778  */
779  virtual ErrorCode get_entities_by_type( const EntityHandle meshset,
780  const EntityType type,
781  std::vector< EntityHandle >& entities,
782  const bool recursive = false ) const = 0;
783 
784  //! Retrieve entities in the database or meshset which have any or all of the tag(s) and
785  //! (optionally) value(s) specified.
786  /** \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
787  \param type Type of entities to be returned
788  \param tag_handles Vector of tag handles entities must have
789  \param values Vector of pointers to values of tags in <em>tag_handles</em>
790  \param num_tags Number of tags and values in <em>tag_handles</em> and <em>values</em>
791  \param entities Range in which entities are returned.
792  \param condition Boolean condition, either Interface::UNION or Interface::INTERSECT
793  \param recursive If true, meshsets containing meshsets are queried recursively. Returns
794  the contents of meshsets, but not the meshsets themselves. Specifying
795  both recursive=true and type=MBENTITYSET is an error, as it would always
796  result in an empty list.
797 
798  If Interface::UNION is specified as the condition, entities with <em>any</em> of the tags
799  and values specified are returned. If Interface::INTERSECT is specified, only entities with
800  <em>all</em> of the tags/values are returned.
801 
802  If <em>values</em> is NULL, entities with the specified tags and any corresponding values
803  are returned. Note that if <em>values</em> is non-NULL, it is a vector of <em>pointers</em>
804  to tag values.
805 
806  Example: \code
807  // get the dirichlet sets in a mesh
808  Range dir_sets;
809  Tag dir_tag;
810  tag_get_handle(DIRICHLET_SET_TAG_NAME, dir_tag, 1, MB_TYPE_INTEGER);
811  get_entities_by_type_and_tag(0, MBENTITYSET, &dir_tag, NULL, 1, dir_sets,
812  Interface::UNION);
813  \endcode
814  */
815  virtual ErrorCode get_entities_by_type_and_tag( const EntityHandle meshset,
816  const EntityType type,
817  const Tag* tag_handles,
818  const void* const* values,
819  const int num_tags,
820  Range& entities,
821  const int condition = Interface::INTERSECT,
822  const bool recursive = false ) const = 0;
823 
824  //! Returns all entities in the data base or meshset, in a range (order not preserved)
825  /** Appends entities to list passed in.
826  \param meshset Meshset whose entities are being queried (zero if query is for the entire
827  mesh). \param entities Range in which entities are returned. \param recursive If true,
828  meshsets containing meshsets are queried recursively. Returns the contents of meshsets, but
829  not the meshsets themselves if true.
830 
831  Example: \code
832  Range entities;
833  // get all non-meshset entities in meshset, including in contained meshsets
834  get_entities_by_handle(meshset, entities, true);
835  \endcode
836  */
837  virtual ErrorCode get_entities_by_handle( const EntityHandle meshset,
838  Range& entities,
839  const bool recursive = false ) const = 0;
840 
841  //! Returns all entities in the data base or meshset, in a vector (order preserved)
842  /** Appends entities to list passed in.
843  \param meshset Meshset whose entities are being queried (zero if query is for the entire
844  mesh). \param entities STL vector in which entities are returned. \param recursive If true,
845  meshsets containing meshsets are queried recursively. Returns the contents of meshsets, but
846  not the meshsets themselves if true.
847 
848  Example: \code
849  std::vector<EntityHandle> entities;
850  // get all non-meshset entities in meshset, including in contained meshsets
851  get_entities_by_handle(meshset, entities, true);
852  \endcode
853  */
854  virtual ErrorCode get_entities_by_handle( const EntityHandle meshset,
855  std::vector< EntityHandle >& entities,
856  const bool recursive = false ) const = 0;
857 
858  //! Return the number of entities of given dimension in the database or meshset
859  /** \param meshset Meshset whose entities are being queried (zero if query is for the entire
860  mesh). \param dimension Dimension of entities desired. \param num_entities Number of entities
861  of the given dimension \param recursive If true, meshsets containing meshsets are queried
862  recursively. Returns the contents of meshsets, but not the meshsets themselves if true.
863  */
864  virtual ErrorCode get_number_entities_by_dimension( const EntityHandle meshset,
865  const int dimension,
866  int& num_entities,
867  const bool recursive = false ) const = 0;
868 
869  //! Retrieve the number of entities of a given type in the database or meshset.
870  /** Identical to get_entities_by_dimension, except returns number instead of entities
871  \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
872  \param type Type of entities to be returned
873  \param num_entities Number of entities of type <em>type</em>
874  \param recursive If true, meshsets containing meshsets are queried recursively. Returns
875  the contents of meshsets, but not the meshsets themselves. Specifying
876  both recursive=true and type=MBENTITYSET is an error, as it would always
877  result in an empty list.
878  */
879  virtual ErrorCode get_number_entities_by_type( const EntityHandle meshset,
880  const EntityType type,
881  int& num_entities,
882  const bool recursive = false ) const = 0;
883 
884  //! Retrieve number of entities in the database or meshset which have any or all of the
885  //! tag(s) and (optionally) value(s) specified.
886  /** Identical to get_entities_by_type_and_tag, except number instead of entities are returned
887  \param meshset Meshset whose entities are being queried (zero if query is for entire mesh).
888  \param type Type of entities to be returned
889  \param tag_handles Vector of tag handles entities must have
890  \param values Vector of pointers to values of tags in <em>tag_handles</em>
891  \param num_tags Number of tags and values in <em>tag_handles</em> and <em>values</em>
892  \param num_entities Range in which number of entities are returned.
893  \param recursive If true, meshsets containing meshsets are queried recursively. Returns
894  the contents of meshsets, but not the meshsets themselves. Specifying
895  both recursive=true and type=MBENTITYSET is an error, as it would always
896  result in an empty list.
897  */
898  virtual ErrorCode get_number_entities_by_type_and_tag( const EntityHandle meshset,
899  const EntityType type,
900  const Tag* tag_handles,
901  const void* const* values,
902  const int num_tags,
903  int& num_entities,
904  const int condition = Interface::INTERSECT,
905  const bool recursive = false ) const = 0;
906 
907  //! Returns number of entities in the data base or meshset
908  /** Identical to get-entities_by_handle, except number instead of entities are returned
909  \param meshset Meshset whose entities are being queried (zero if query is for the entire
910  mesh). \param num_entities Range in which num_entities are returned. \param recursive If
911  true, meshsets containing meshsets are queried recursively. Returns the contents of
912  meshsets, but not the meshsets themselves if true.
913  */
914  virtual ErrorCode get_number_entities_by_handle( const EntityHandle meshset,
915  int& num_entities,
916  const bool recursive = false ) const = 0;
917 
918  /**@}*/
919 
920  /** \name Mesh modification */
921 
922  /**@{*/
923 
924  //! Create an element based on the type and connectivity.
925  /** Create a new element in the database. Vertices composing this element must already exist,
926  and connectivity must be specified in canonical order for the given element type. If
927  connectivity vector is not correct for EntityType <em>type</em> (ie, a vector with
928  3 vertices is passed in to make an MBQUAD), the function returns MB_FAILURE.
929  \param type Type of element to create. (MBTET, MBTRI, MBKNIFE, etc.)
930  \param connectivity 1d vector containing connectivity of element to create.
931  \param num_vertices Number of vertices in element
932  \param element_handle Handle representing the newly created element in the database.
933 
934  Example: \code
935  EntityHandle quad_conn[] = {vertex0, vertex1, vertex2, vertex3};
936  EntityHandle quad_handle = 0;
937  create_element( MBQUAD, quad_conn, 4, quad_handle ); \endcode
938  */
939  virtual ErrorCode create_element( const EntityType type,
940  const EntityHandle* connectivity,
941  const int num_vertices,
942  EntityHandle& element_handle ) = 0;
943 
944  //! Creates a vertex with the specified coordinates.
945  /**
946  \param coordinates Array that has 3 doubles in it.
947  \param entity_handle EntityHandle representing the newly created vertex in the database.
948 
949  Example: \code
950  double coordinates[] = {1.034, 23.23, -0.432};
951  EntityHandle new_handle = 0;
952  create_vertex( coordinates, entity_handle ); \endcode
953  */
954  virtual ErrorCode create_vertex( const double coordinates[3], EntityHandle& entity_handle ) = 0;
955 
956  //! Create a set of vertices with the specified coordinates
957  /**
958  \param coordinates Array that has 3*n doubles in it.
959  \param nverts Number of vertices to create
960  \param entity_handles Range passed back with new vertex handles
961  */
962  virtual ErrorCode create_vertices( const double* coordinates, const int nverts, Range& entity_handles ) = 0;
963 
964  //! Merge two entities into a single entity
965  /** Merge two entities into a single entities, with <em>entity_to_keep</em> receiving
966  adjacencies that were on <em>entity_to_remove</em>.
967  \param entity_to_keep Entity to be kept after merge
968  \param entity_to_remove Entity to be merged into <em>entity_to_keep</em>
969  \param auto_merge If false, <em>entity_to_keep</em> and <em>entity_to_remove</em> must share
970  the same lower-dimensional entities; if true, MB tries to merge those entities automatically
971  \param delete_removed_entity If true, <em>entity_to_remove</em> is deleted after merge is
972  complete
973  */
974  virtual ErrorCode merge_entities( EntityHandle entity_to_keep,
975  EntityHandle entity_to_remove,
976  bool auto_merge,
977  bool delete_removed_entity ) = 0;
978 
979  //! Removes entities in a vector from the data base.
980  /** If any of the entities are contained in any meshsets, it is removed from those meshsets
981  which were created with MESHSET_TRACK_OWNER option bit set. Tags for <em>entity</em> are
982  removed as part of this function.
983  \param entities 1d vector of entities to delete
984  \param num_entities Number of entities in 1d vector
985  */
986  virtual ErrorCode delete_entities( const EntityHandle* entities, const int num_entities ) = 0;
987 
988  //! Removes entities in a range from the data base.
989  /** If any of the entities are contained in any meshsets, it is removed from those meshsets
990  which were created with MESHSET_TRACK_OWNER option bit set. Tags for <em>entity</em> are
991  removed as part of this function.
992  \param entities Range of entities to delete
993  */
994  virtual ErrorCode delete_entities( const Range& entities ) = 0;
995 
996  /**@}*/
997 
998  /** \name Information */
999 
1000  /**@{*/
1001 
1002  //! List entities to standard output
1003  /** Lists all data pertaining to entities (i.e. vertex coordinates if vertices, connectivity if
1004  elements, set membership if set). Useful for debugging, but output can become quite long
1005  for large databases.
1006  */
1007  virtual ErrorCode list_entities( const Range& entities ) const = 0;
1008 
1009  //! List entities, or number of entities in database, to standard output
1010  /** Lists data pertaining to entities to standard output. If <em>entities</em> is NULL and
1011  <em>num_entities</em> is zero, lists only the number of entities of each type in the
1012  database. If <em>entities</em> is NULL and <em>num_entities</em> is non-zero, lists all
1013  information for all entities in the database.
1014  \param entities 1d vector of entities to list
1015  \param num_entities Number of entities in 1d vector
1016  */
1017  virtual ErrorCode list_entities( const EntityHandle* entities, const int num_entities ) const = 0;
1018 
1019  //! List a single entity; no header printed
1020  /** Lists a single entity, including its connectivity and its adjacencies.
1021  * No header is printed, because calling function might print information between header
1022  * and information printed by this function.
1023  * \param entity The entity to be listed.
1024  */
1025  virtual ErrorCode list_entity( const EntityHandle entity ) const = 0;
1026 
1027  //! Return information about the last error
1028  /** \param info std::string into which information on the last error is written.
1029  */
1030  virtual ErrorCode get_last_error( std::string& info ) const = 0;
1031 
1032  //! Return string representation of given error code
1033  /** \param code Error code for which string is wanted
1034  */
1035  virtual std::string get_error_string( const ErrorCode code ) const = 0;
1036 
1037  /**\brief Calculate amount of memory used to store MOAB data
1038  *
1039  * This function calculates the amount of memory used to store
1040  * MOAB data.
1041  *
1042  * There are two possible values for each catagory of memory use.
1043  * The exact value and the amortized value. The exact value is the
1044  * amount of memory used to store the data for the specified entities.
1045  * The amortized value includes the exact value and an amortized
1046  * estimate of the memory consumed in overhead for storing the values
1047  * (indexing structures, access structures, etc.)
1048  *
1049  * Note: If ent_array is NULL and total_amortized_storage is *not* NULL,
1050  * the total memory used by MOAB for storing data all will be
1051  * returned in the address pointed to by total_amortized_storage.
1052  *
1053  *\param ent_array Array of entities for which to estimate the memory use.
1054  * If NULL, estimate is done for all entities.
1055  *\param num_ents The length of ent_array. Not used if ent_rray is NULL.
1056  *\param total_(amortized_)storage The sum of the memory entity, adjacency,
1057  * and all tag storage.
1058  *\param (amortized_)entity_storage The storage for the entity definitions
1059  * (connectivity arrays for elements, coordinates for
1060  * vertices, list storage within sets, etc.)
1061  *\param (amortized_)adjacency_storage The storage for adjacency data.
1062  *\param tag_array An array of tags for which to calculate the memory use.
1063  *\param num_tags The lenght of tag_array
1064  *\param (amortized_)tag_storage If tag_array is not NULL, then one value
1065  * for each tag specifying the memory used for storing
1066  * that tag. If tag_array is NULL and this value is not,
1067  * the location at which to store the total memory used
1068  * for all tags.
1069  */
1070  virtual void estimated_memory_use( const EntityHandle* ent_array = 0,
1071  unsigned long num_ents = 0,
1072  unsigned long long* total_storage = 0,
1073  unsigned long long* total_amortized_storage = 0,
1074  unsigned long long* entity_storage = 0,
1075  unsigned long long* amortized_entity_storage = 0,
1076  unsigned long long* adjacency_storage = 0,
1077  unsigned long long* amortized_adjacency_storage = 0,
1078  const Tag* tag_array = 0,
1079  unsigned num_tags = 0,
1080  unsigned long long* tag_storage = 0,
1081  unsigned long long* amortized_tag_storage = 0 ) = 0;
1082 
1083  /**\brief Calculate amount of memory used to store MOAB data
1084  *
1085  * This function calculates the amount of memory used to store
1086  * MOAB data.
1087  *
1088  * There are two possible values for each catagory of memory use.
1089  * The exact value and the amortized value. The exact value is the
1090  * amount of memory used to store the data for the specified entities.
1091  * The amortized value includes the exact value and an amortized
1092  * estimate of the memory consumed in overhead for storing the values
1093  * (indexing structures, access structures, etc.)
1094  *
1095  *\param ents Entities for which to estimate the memory use.
1096  *\param total_(amortized_)storage The sum of the memory entity, adjacency,
1097  * and all tag storage.
1098  *\param (amortized_)entity_storage The storage for the entity definitions
1099  * (connectivity arrays for elements, coordinates for
1100  * vertices, list storage within sets, etc.)
1101  *\param (amortized_)adjacency_storage The storage for adjacency data.
1102  *\param tag_array An array of tags for which to calculate the memory use.
1103  *\param num_tags The lenght of tag_array
1104  *\param (amortized_)tag_storage If tag_array is not NULL, then one value
1105  * for each tag specifying the memory used for storing
1106  * that tag. If tag_array is NULL and this value is not,
1107  * the location at which to store the total memory used
1108  * for all tags.
1109  */
1110  virtual void estimated_memory_use( const Range& ents,
1111  unsigned long long* total_storage = 0,
1112  unsigned long long* total_amortized_storage = 0,
1113  unsigned long long* entity_storage = 0,
1114  unsigned long long* amortized_entity_storage = 0,
1115  unsigned long long* adjacency_storage = 0,
1116  unsigned long long* amortized_adjacency_storage = 0,
1117  const Tag* tag_array = 0,
1118  unsigned num_tags = 0,
1119  unsigned long long* tag_storage = 0,
1120  unsigned long long* amortized_tag_storage = 0 ) = 0;
1121  /**@}*/
1122 
1123  /** \name Higher-order elements */
1124 
1125  /**@{*/
1126 
1127  //! function object for recieving events from MB of higher order nodes added to entities
1128  class MOAB_EXPORT HONodeAddedRemoved
1129  {
1130  public:
1131  //! Constructor
1132  HONodeAddedRemoved() {}
1133 
1134  //! Destructor
1135  virtual ~HONodeAddedRemoved() {}
1136 
1137  //! node_added called when a node was added to an element's connectivity array
1138  //! note: connectivity array of element may be incomplete (corner nodes will exist always)
1139  /**
1140  * \param node Node being added
1141  * \param element Element node is being added to
1142  */
1143  virtual void node_added( EntityHandle node, EntityHandle element ) = 0;
1144 
1145  //! node_added called when a node was added to an element's connectivity array
1146  //! note: connectivity array of element may be incomplete (corner nodes will exist always)
1147  /**
1148  * \param node Node being removed.
1149  */
1150  virtual void node_removed( EntityHandle node ) = 0;
1151  };
1152 
1153  //! Convert entities to higher-order elements by adding mid nodes
1154  /** This function causes MB to create mid-nodes on all edges, faces, and element interiors
1155  for all entities in <em>meshset</em>. Higher order nodes appear in an element's
1156  connectivity array according to the algorithm described in the documentation for Mesh. If
1157  <em>HONodeAddedRemoved</em> function is input, this function is called to notify the
1158  application of nodes being added/removed from the mesh. \param meshset The set of entities
1159  being converted \param mid_edge If true, mid-edge nodes are created \param mid_face If true,
1160  mid-face nodes are created \param mid_region If true, mid-element nodes are created \param
1161  function_object If non-NULL, the node_added or node_removed functions on this object are
1162  called when nodes are added or removed from an entity, respectively
1163  */
1164  virtual ErrorCode convert_entities( const EntityHandle meshset,
1165  const bool mid_edge,
1166  const bool mid_face,
1167  const bool mid_region,
1168  HONodeAddedRemoved* function_object = 0 ) = 0;
1169 
1170  //! Returns the side number, in canonical ordering, of <em>child</em> with respect to
1171  //! <em>parent</em>
1172  /** Given a parent and child entity, returns the canonical ordering information side number,
1173  sense, and offset of <em>child</em> with respect to <em>parent</em>. This function returns
1174  MB_FAILURE if <em>child</em> is not related to <em>parent</em>. This function does *not*
1175  create adjacencies between <em>parent</em> and <em>child</em>.
1176  \param parent Parent entity to be compared
1177  \param child Child entity to be compared
1178  \param side_number Side number in canonical ordering of <em>child</em> with respect to
1179  <em>parent</em>
1180  \param sense Sense of <em>child</em> with respect to <em>parent</em>, assuming ordering of
1181  <em>child</em> as given by get_connectivity called on <em>child</em>; sense is 1, -1
1182  for forward/reverse sense, resp.
1183  \param offset Offset between first vertex of <em>child</em> and first vertex of side
1184  <em>side_number</em> on <em>parent</em>
1185  */
1186  virtual ErrorCode side_number( const EntityHandle parent,
1187  const EntityHandle child,
1188  int& side_number,
1189  int& sense,
1190  int& offset ) const = 0;
1191 
1192  //! Find the higher-order node on a subfacet of an entity
1193  /** Given an entity and the connectivity and type of one of its subfacets, find the
1194  high order node on that subfacet, if any. The number of vertices in <em>subfacet_conn</em>
1195  is derived from <em>subfacet_type</em> and the canonical numbering for that type.
1196  \param parent_handle The element whose subfacet is being queried
1197  \param subfacet_conn The connectivity of the subfacet being queried
1198  \param subfacet_type The type of subfacet being queried
1199  \param high_order_node If the subfacet has a high-order node defined on
1200  <em>parent_handle</em>, the handle for that node.
1201  */
1202  virtual ErrorCode high_order_node( const EntityHandle parent_handle,
1203  const EntityHandle* subfacet_conn,
1204  const EntityType subfacet_type,
1205  EntityHandle& high_order_node ) const = 0;
1206 
1207  //! Return the handle of the side element of a given dimension and index
1208  /** Given a parent entity and a target dimension and side number, return the handle of
1209  the entity corresponding to that side. If an entity has not been created to represent
1210  that side, one is not created by this function, and zero is returned in
1211  <em>target_entity</em>. \param source_entity The entity whose side is being queried. \param
1212  dim The topological dimension of the side being queried. \param side_number The canonical
1213  index of the side being queried. \param target_entity The handle of the entity representing
1214  this side, if any.
1215  */
1216  virtual ErrorCode side_element( const EntityHandle source_entity,
1217  const int dim,
1218  const int side_number,
1219  EntityHandle& target_entity ) const = 0;
1220 
1221  /**@}*/
1222 
1223  /** \name Tags */
1224 
1225  /**@{*/
1226 
1227  /**\brief Get a tag handle, possibly creating the tag
1228  *
1229  * Get a handle used to associate application-defined values
1230  * with MOAB entities. If the tag does not already exist then
1231  * \c flags should contain exactly one of \c MB_TAG_SPARSE,
1232  * \c MB_TAG_DENSE, \c MB_TAG_MESH unless \c type is MB_TYPE_BIT,
1233  * which implies \c MB_TAG_BIT storage.
1234  * .
1235  *\param name The tag name
1236  *\param size Tag size as number of values of of data type per entity
1237  * (or number of bytes if \c MB_TAG_BYTES is passed in flags). If \c
1238  *MB_TAG_VARLEN is specified, this value is taken to be the size of the default value if one is
1239  *specified and is otherwise ignored. \param type The type of the data (used for IO)
1240  *\param tag_handle Output: the resulting tag handle.
1241  *\param flags Bitwise OR of values from TagType
1242  *\param default_value Optional default value for tag.
1243  *\param created Optional returned boolean indicating that the tag
1244  * was created.
1245  *\return - \c MB_ALREADY_ALLOCATED if tag exists and \c MB_TAG_EXCL is specified, or
1246  *default values do not match (and \c MB_TAG_ANY or \c MB_TAG_DFTOK not specified).
1247  * - \c MB_TAG_NOT_FOUND if tag does not exist and \c MB_TAG_CREAT is not
1248  *specified
1249  * - \c MB_INVALID_SIZE if tag value size is not a multiple of the size of the
1250  *data type (and \c MB_TAG_ANY not specified).
1251  * - \c MB_TYPE_OUT_OF_RANGE invalid or inconsistent parameter
1252  * - \c MB_VARIABLE_DATA_LENGTH if \c MB_TAG_VARLEN and \c default_value is non-null and
1253  * \c default_value_size is not specified.
1254  *
1255  *\note A call to tag_get_handle that includes a default value will fail
1256  * if the tag already exists with a different default value. A call without
1257  * a default value will succeed if the tag already exists, regardless of
1258  * whether or not the existing tag has a default value.
1259  *
1260  * Examples:
1261  *
1262  * Retrieve a handle for an existing tag, returning a non-success error
1263  * code if the tag does not exist or does not store 1 integer value per
1264  * entity:
1265  *\code
1266  * Tag git_tag;
1267  * mb.tag_get_handle( GLOBAL_ID_TAG_NAME, 1, MB_TYPE_INTEGER, gid_tag );
1268  * \endcode
1269  * Get the tag handle, or create it as a dense tag if it does not already
1270  * exist:
1271  *\code
1272  * Tag gid_tag;
1273  * mb.tag_get_handle( GLOBAL_ID_TAG_NAME, 1, MB_TYPE_INTEGER, gid_tag, MB_TAG_CREAT|MB_TAG_BIT
1274  *); \endcode Create the tag or *fail* if it already exists: \code Tag gid_tag;
1275  * mb.tag_get_handle( GLOBAL_ID_TAG_NAME, 1, MB_TYPE_INTEGER, gid_tag, MB_TAG_EXCL|MB_TAG_DENSE
1276  *); \endcode Get an existing variable length tag, failing if it does not exist or is not
1277  *variable-length or does not contain double values. \code Tag vtag; mb.tag_get_handle(
1278  *tag_name, 0, MB_TYPE_DOUBLE, vtag ); \endcode Get the same variable-length tag, but create it
1279  *with a default value if it doesn't exist. Note that if the tag already exists this call will
1280  *return a non-success error code if the existing tag has a different default value. \code Tag
1281  *vtag; const double default_val = M_PI; const int def_val_len = 1; mb.tag_get_handle( tag_name,
1282  *def_val_len, MB_TYPE_DOUBLE, vtag, MB_TAG_SPARSE|MB_TAG_VARLEN|MB_TAG_CREAT, &default_val );
1283  * \endcode
1284  */
1285  virtual ErrorCode tag_get_handle( const char* name,
1286  int size,
1287  DataType type,
1288  Tag& tag_handle,
1289  unsigned flags = 0,
1290  const void* default_value = 0,
1291  bool* created = 0 ) = 0;
1292 
1293  /**\brief same as non-const version, except that MB_TAG_CREAT flag is ignored. */
1294  virtual ErrorCode tag_get_handle( const char* name,
1295  int size,
1296  DataType type,
1297  Tag& tag_handle,
1298  unsigned flags = 0,
1299  const void* default_value = 0 ) const = 0;
1300 
1301  //! Get the name of a tag corresponding to a handle
1302  /** \param tag_handle Tag you want the name of.
1303  \param tag_name Name string for <em>tag_handle</em>.
1304  */
1305  virtual ErrorCode tag_get_name( const Tag tag_handle, std::string& tag_name ) const = 0;
1306 
1307  /**\brief Gets the tag handle corresponding to a name
1308 
1309  If a tag of that name does not exist, returns MB_TAG_NOT_FOUND
1310  \param tag_name Name of the desired tag.
1311  \param tag_handle Tag handle corresponding to <em>tag_name</em>
1312  */
1313  virtual ErrorCode tag_get_handle( const char* tag_name, Tag& tag_handle ) const = 0;
1314 
1315  //! Get the size of the specified tag in bytes
1316  /** Get the size of the specified tag, in bytes (MB_TAG_SPARSE, MB_TAG_DENSE, MB_TAG_MESH)
1317  \note always returns 1 for bit tags.
1318  \param tag Handle of the desired tag.
1319  \param bytes_per_tag Size of the specified tag
1320  \return - MB_TAG_NOT_FOUND for invalid tag handles
1321  - MB_VARIABLE_DATA_LENGTH for variable-length tags
1322  - MB_SUCCESS otherwise
1323  */
1324  virtual ErrorCode tag_get_bytes( const Tag tag, int& bytes_per_tag ) const = 0;
1325 
1326  //! Get the array length of a tag
1327  /** Get the size of the specified tag, in as the number of values of
1328  the basic type (e.g. number of integer values for each tag value if
1329  the data type is MB_TYPE_INTEGER). Gives number of bits for bit tags
1330  and is the same as \c tag_get_bytes for MB_TYPE_OPAQUE tags.
1331  \param tag Handle of the desired tag.
1332  \param length Size of the specified tag
1333  \return - MB_TAG_NOT_FOUND for invalid tag handles
1334  - MB_VARIABLE_DATA_LENGTH for variable-length tags
1335  - MB_SUCCESS otherwise
1336  */
1337  virtual ErrorCode tag_get_length( const Tag tag, int& length ) const = 0;
1338 
1339  //! Get the type of the specified tag
1340  /** Get the type of the specified tag
1341  \param tag Handle of the desired tag.
1342  \param tag_type Type of the specified tag
1343  */
1344  virtual ErrorCode tag_get_type( const Tag tag, TagType& tag_type ) const = 0;
1345 
1346  /** \brief Get data type of tag.
1347  *
1348  * Get the type of the tag data. The tag is data is assumed to
1349  * be a vector of this type. If the tag data vetcor contains
1350  * more than one value, then the tag size must be a multiple of
1351  * the size of this type.
1352  * \param tag The tag
1353  * \param type The type of the specified tag (output).
1354  */
1355  virtual ErrorCode tag_get_data_type( const Tag tag, DataType& type ) const = 0;
1356 
1357  //! Get the default value of the specified tag
1358  /** Get the default value of the specified tag
1359  \param tag Handle of the desired tag.
1360  \param def_value Pointer to memory where default value of the specified tag is written
1361  \return - MB_ENTITY_NOT_FOUND If no default value is set for tag.
1362  - MB_SUCCESS If success.
1363  - MB_FAILURE If <code>def_val</code> is NULL.
1364  - MB_TAG_NOT_FOUND If <code>tag_handle</code> is invalid.
1365  */
1366  virtual ErrorCode tag_get_default_value( const Tag tag, void* def_val ) const = 0;
1367  virtual ErrorCode tag_get_default_value( Tag tag, const void*& def_val, int& size ) const = 0;
1368 
1369  //! Get handles for all tags defined in the mesh instance
1370  /** Get handles for all tags defined on the mesh instance.
1371  \param tag_handles STL vector of all tags
1372  */
1373  virtual ErrorCode tag_get_tags( std::vector< Tag >& tag_handles ) const = 0;
1374 
1375  //! Get handles for all tags defined on this entity
1376  /** Get handles for all tags defined on this entity; if zero, get all tags defined
1377  on mesh instance
1378  \param entity Entity for which you want tags
1379  \param tag_handles STL vector of all tags defined on <em>entity</em>
1380  */
1381  virtual ErrorCode tag_get_tags_on_entity( const EntityHandle entity, std::vector< Tag >& tag_handles ) const = 0;
1382 
1383  //! Get the value of the indicated tag on the specified entities in the specified vector
1384  /** Get the value of the indicated tag on the specified entities; <em>tag_data</em> must contain
1385  enough space (i.e. tag_size*num_entities bytes) to hold all tag data. MOAB does
1386  <em>not</em> check whether this space is available before writing to it. \note For bit tags,
1387  tag_data must contain one byte per entity. For each entity, the corresponding byte will
1388  contain the tag bits in the lower bit positions and zero bits in the higher. \param
1389  tag_handle Tag whose values are being queried. \param entity_handles 1d vector of entity
1390  handles whose tag values are being queried \param num_entities Number of entities in 1d
1391  vector of entity handles \param tag_data Pointer to memory into which tag data will be
1392  written
1393  */
1394  virtual ErrorCode tag_get_data( const Tag tag_handle,
1395  const EntityHandle* entity_handles,
1396  int num_entities,
1397  void* tag_data ) const = 0;
1398 
1399  //! Get the value of the indicated tag on the specified entities in the specified range
1400  /** Identical to previous function, except entities are specified using a range instead of a 1d
1401  vector. \param tag_handle Tag whose values are being queried. \param entity_handles Range of
1402  entity handles whose tag values are being queried \param tag_data Pointer to memory into
1403  which tag data will be written
1404  */
1405  virtual ErrorCode tag_get_data( const Tag tag_handle, const Range& entity_handles, void* tag_data ) const = 0;
1406 
1407  //! Set the value of the indicated tag on the specified entities in the specified vector
1408  /** Set the value of the indicated tag on the specified entities; <em>tag_data</em> contains the
1409  values, <em>one value per entity in <em>entity_handles</em></em>.
1410  \note For bit tags, tag_data must contain one byte per entity. For each
1411  entity, the tag bits will be read from the lower bits of the
1412  corresponding byte.
1413  \param tag_handle Tag whose values are being set
1414  \param entity_handles 1d vector of entity handles whose tag values are being set
1415  \param num_entities Number of entities in 1d vector of entity handles
1416  \param tag_data Pointer to memory holding tag values to be set, <em>one entry per entity
1417  handle</em>
1418  */
1419  virtual ErrorCode tag_set_data( Tag tag_handle,
1420  const EntityHandle* entity_handles,
1421  int num_entities,
1422  const void* tag_data ) = 0;
1423 
1424  //! Set the value of the indicated tag on the specified entities in the specified range
1425  /** Identical to previous function, except entities are specified using a range instead of a 1d
1426  vector. \param tag_handle Tag whose values are being set \param entity_handles Range of
1427  entity handles whose tag values are being set \param tag_data Pointer to memory holding tag
1428  values to be set, <em>one entry per entity handle</em>
1429  */
1430  virtual ErrorCode tag_set_data( Tag tag_handle, const Range& entity_handles, const void* tag_data ) = 0;
1431 
1432  /**\brief Get pointers to tag data
1433  *
1434  * For a tag, get the values for a list of passed entity handles.
1435  *\note This function may not be used for bit tags.
1436  *\param tag_handle The tag
1437  *\param entity_handles An array of entity handles for which to retreive tag values.
1438  *\param num_entities The length of the 'entity_handles' array.
1439  *\param tag_data An array of 'const void*'. Array must be at least
1440  * 'num_entitities' long. Array is populated (output)
1441  * with pointers to the internal storage for the
1442  * tag value corresponding to each entity handle.
1443  *\param tag_sizes The length of each tag value. Optional for
1444  * fixed-length tags. Required for variable-length tags.
1445  */
1446  virtual ErrorCode tag_get_by_ptr( const Tag tag_handle,
1447  const EntityHandle* entity_handles,
1448  int num_entities,
1449  const void** tag_data,
1450  int* tag_sizes = 0 ) const = 0;
1451 
1452  /**\brief Get pointers to tag data
1453  *
1454  * For a tag, get the values for a list of passed entity handles.
1455  *\note This function may not be used for bit tags.
1456  *\param tag_handle The tag
1457  *\param entity_handles The entity handles for which to retreive tag values.
1458  *\param tag_data An array of 'const void*'. Array is populated (output)
1459  * with pointers to the internal storage for the
1460  * tag value corresponding to each entity handle.
1461  *\param tag_sizes The length of each tag value. Optional for
1462  * fixed-length tags. Required for variable-length tags.
1463  */
1464  virtual ErrorCode tag_get_by_ptr( const Tag tag_handle,
1465  const Range& entity_handles,
1466  const void** tag_data,
1467  int* tag_sizes = 0 ) const = 0;
1468 
1469  /**\brief Set tag data given an array of pointers to tag values.
1470  *
1471  * For a tag, set the values for a list of passed entity handles.
1472  *\note This function may not be used for bit tags.
1473  *\param tag_handle The tag
1474  *\param entity_handles An array of entity handles for which to set tag values.
1475  *\param num_entities The length of the 'entity_handles' array.
1476  *\param tag_data An array of 'const void*'. Array must be at least
1477  * 'num_entitities' long. Array is expected to
1478  * contain pointers to tag values for the corresponding
1479  * EntityHandle in 'entity_handles'.
1480  *\param tag_sizes The length of each tag value. Optional for
1481  * fixed-length tags. Required for variable-length tags.
1482  */
1483  virtual ErrorCode tag_set_by_ptr( Tag tag_handle,
1484  const EntityHandle* entity_handles,
1485  int num_entities,
1486  void const* const* tag_data,
1487  const int* tag_sizes = 0 ) = 0;
1488 
1489  /**\brief Set tag data given an array of pointers to tag values.
1490  *
1491  * For a tag, set the values for a list of passed entity handles.
1492  *\note This function may not be used for bit tags.
1493  *\param tag_handle The tag
1494  *\param entity_handles The entity handles for which to set tag values.
1495  *\param tag_data An array of 'const void*'. Array is expected to
1496  * contain pointers to tag values for the corresponding
1497  * EntityHandle in 'entity_handles'.
1498  *\param tag_sizes The length of each tag value. Optional for
1499  * fixed-length tags. Required for variable-length tags.
1500  */
1501  virtual ErrorCode tag_set_by_ptr( Tag tag_handle,
1502  const Range& entity_handles,
1503  void const* const* tag_data,
1504  const int* tag_sizes = 0 ) = 0;
1505 
1506  /**\brief Set tag data given value.
1507  *
1508  * For a tag, set the values for a list of passed entity handles to
1509  * the same, specified value.
1510  *
1511  *\param tag_handle The tag
1512  *\param entity_handles The entity handles for which to set tag values.
1513  *\param tag_data A pointer to the tag value.
1514  *\param tag_sizes For variable-length tags, the length of the
1515  * tag value. This argument will be ignored for
1516  * fixed-length tags.
1517  */
1518  virtual ErrorCode tag_clear_data( Tag tag_handle,
1519  const Range& entity_handles,
1520  const void* value,
1521  int value_size = 0 ) = 0;
1522 
1523  /**\brief Set tag data given value.
1524  *
1525  * For a tag, set the values for a list of passed entity handles to
1526  * the same, specified value.
1527  *
1528  *\param tag_handle The tag
1529  *\param entity_handles The entity handles for which to set tag values.
1530  *\param tag_data A pointer to the tag value.
1531  *\param tag_sizes For variable-length tags, the length of the
1532  * tag value. This argument will be ignored for
1533  * fixed-length tags.
1534  */
1535  virtual ErrorCode tag_clear_data( Tag tag_handle,
1536  const EntityHandle* entity_handles,
1537  int num_entity_handles,
1538  const void* value,
1539  int value_size = 0 ) = 0;
1540 
1541  //! Delete the data of a vector of entity handles and sparse tag
1542  /** Delete the data of a tag on a vector of entity handles. Only sparse tag data are deleted
1543  with this function; dense tags are deleted by deleting the tag itself using tag_delete.
1544  \param tag_handle Handle of the (sparse) tag being deleted from entity
1545  \param entity_handles 1d vector of entity handles from which the tag is being deleted
1546  \param num_handles Number of entity handles in 1d vector
1547  */
1548  virtual ErrorCode tag_delete_data( Tag tag_handle, const EntityHandle* entity_handles, int num_handles ) = 0;
1549 
1550  //! Delete the data of a range of entity handles and sparse tag
1551  /** Delete the data of a tag on a range of entity handles. Only sparse tag data are deleted
1552  with this function; dense tags are deleted by deleting the tag itself using tag_delete.
1553  \param tag_handle Handle of the (sparse) tag being deleted from entity
1554  \param entity_range Range of entities from which the tag is being deleted
1555  */
1556  virtual ErrorCode tag_delete_data( Tag tag_handle, const Range& entity_range ) = 0;
1557 
1558  /**\brief Access tag data via direct pointer into contiguous blocks
1559  *
1560  * Iteratively obtain direct access to contiguous blocks of tag
1561  * storage. This function cannot be used with bit tags because
1562  * of the compressed bit storage. This function cannot be used
1563  * with variable length tags because it does not provide a mechanism
1564  * to determine the length of the value for each entity. This
1565  * function may be used with sparse tags, but if it is used, it
1566  * will return data for a single entity at a time.
1567  *
1568  *\param tag_handle The handle of the tag for which to access data
1569  *\param iter The first entity for which to return data.
1570  *\param end One past the last entity for which data is desired.
1571  *\param count The number of entities for which data was returned
1572  *\param data_ptr Output: pointer to tag storage.
1573  *\param allocate If true, space for this tag will be allocated, if not it wont
1574  *
1575  *\note If this function is called for entities for which no tag value
1576  * has been set, but for which a default value exists, it will
1577  * force the allocation of explicit storage for each such entity
1578  * even though MOAB would normally not explicitly store tag values
1579  * for such entities.
1580  *
1581  *\Example:
1582  *\code
1583  * Range ents; // range to iterate over
1584  * Tag tag; // tag for which to access data
1585  * int bytes;
1586  * ErrorCode err = mb.tag_get_size( tag, bytes );
1587  * if (err) { ... }
1588  *
1589  * ...
1590  * Range::iterator iter = ents.begin();
1591  * while (iter != ents.end()) {
1592  * int count;
1593  * // get contiguous block of tag dat
1594  * void* ptr;
1595  * err = mb.tag_iterate( tag, iter, ents.end(), count, ptr );
1596  * if (err) { ... }
1597  * // do something with tag data
1598  * process_Data( ptr, count );
1599  * // advance to next block of data
1600  * iter += count;
1601  * }
1602  *\endcode
1603  */
1604  virtual ErrorCode tag_iterate( Tag tag_handle,
1605  Range::const_iterator begin,
1606  Range::const_iterator end,
1607  int& count,
1608  void*& data_ptr,
1609  bool allocate = true ) = 0;
1610 
1611  //! Remove a tag from the database and delete all of its associated data
1612  /** Deletes a tag and all associated data.
1613  */
1614  virtual ErrorCode tag_delete( Tag tag_handle ) = 0;
1615 
1616  /**@}*/
1617 
1618  /** \name Sets */
1619 
1620  /**@{*/
1621 
1622  //! Create a new mesh set
1623  /** Create a new mesh set. Meshsets can store entities ordered or unordered. A set can include
1624  entities at most once (MESHSET_SET) or more than once. Meshsets can optionally track its
1625  members using adjacencies (MESHSET_TRACK_OWNER); if set, entities are deleted from tracking
1626  meshsets before being deleted. This adds data to mesh entities, which can be expensive.
1627  \param options Options bitmask for the new meshset, possible values defined above
1628  \param ms_handle Handle for the meshset created
1629  */
1630  virtual ErrorCode create_meshset( const unsigned int options, EntityHandle& ms_handle, int start_id = 0 ) = 0;
1631 
1632  //! Empty a vector of mesh set
1633  /** Empty a mesh set.
1634  \param ms_handles 1d vector of handles of sets being emptied
1635  \param num_meshsets Number of entities in 1d vector
1636  */
1637  virtual ErrorCode clear_meshset( const EntityHandle* ms_handles, const int num_meshsets ) = 0;
1638 
1639  //! Empty a range of mesh set
1640  /** Empty a mesh set.
1641  \param ms_handles Range of handles of sets being emptied
1642  */
1643  virtual ErrorCode clear_meshset( const Range& ms_handles ) = 0;
1644 
1645  //! Get the options of a mesh set
1646  /** Get the options of a mesh set.
1647  \param ms_handle Handle for mesh set being queried
1648  \param options Bit mask in which mesh set options are returned
1649  */
1650  virtual ErrorCode get_meshset_options( const EntityHandle ms_handle, unsigned int& options ) const = 0;
1651 
1652  //! Set the options of a mesh set
1653  /** Set the options of a mesh set.
1654  \param ms_handle Handle for meshset whose options are being changed
1655  \param options Bit mask of options to be used
1656  */
1657  virtual ErrorCode set_meshset_options( const EntityHandle ms_handle, const unsigned int options ) = 0;
1658 
1659  //! Subtract meshsets
1660  /** Subtract <em>meshset2</em> from <em>meshset1</em>, placing the results in meshset1.
1661  \param meshset1 Mesh set being subtracted from, also used to pass back result
1662  \param meshset2 Mesh set being subtracted from <em>meshset1</em>
1663  */
1664  virtual ErrorCode subtract_meshset( EntityHandle meshset1, const EntityHandle meshset2 ) = 0;
1665 
1666  //! Intersect meshsets
1667  /** Intersect <em>meshset1</em> with <em>meshset2</em>, placing the results in meshset1.
1668  \param meshset1 Mesh set being intersected, also used to pass back result
1669  \param meshset2 Mesh set being intersected with <em>meshset1</em>
1670  */
1671  virtual ErrorCode intersect_meshset( EntityHandle meshset1, const EntityHandle meshset2 ) = 0;
1672 
1673  //! Unite meshsets
1674  /** Unite <em>meshset1</em> with <em>meshset2</em>, placing the results in meshset1.
1675  \param meshset1 Mesh set being united, also used to pass back result
1676  \param meshset2 Mesh set being united with <em>meshset1</em>
1677  */
1678  virtual ErrorCode unite_meshset( EntityHandle meshset1, const EntityHandle meshset2 ) = 0;
1679 
1680  //! Add to a meshset entities in specified range
1681  /** Add to a meshset entities in specified range. If <em>meshset</em> has MESHSET_TRACK_OWNER
1682  option set, adjacencies are also added to entities in <em>entities</em>.
1683  \param meshset Mesh set being added to
1684  \param entities Range of entities being added to meshset
1685  */
1686  virtual ErrorCode add_entities( EntityHandle meshset, const Range& entities ) = 0;
1687 
1688  //! Add to a meshset entities in specified vector
1689  /** Add to a meshset entities in specified vector. If <em>meshset</em> has MESHSET_TRACK_OWNER
1690  option set, adjacencies are also added to entities in <em>entities</em>.
1691  \param meshset Mesh set being added to
1692  \param entities 1d vector of entities being added to meshset
1693  \param num_entities Number of entities in 1d vector
1694  */
1695  virtual ErrorCode add_entities( EntityHandle meshset, const EntityHandle* entities, const int num_entities ) = 0;
1696 
1697  //! Remove from a meshset entities in specified range
1698  /** Remove from a meshset entities in specified range. If <em>meshset</em> has
1699  MESHSET_TRACK_OWNER option set, adjacencies in entities in <em>entities</em> are updated.
1700  \param meshset Mesh set being removed from
1701  \param entities Range of entities being removed from meshset
1702  */
1703  virtual ErrorCode remove_entities( EntityHandle meshset, const Range& entities ) = 0;
1704 
1705  //! Remove from a meshset entities in specified vector
1706  /** Remove from a meshset entities in specified vector. If <em>meshset</em> has
1707  MESHSET_TRACK_OWNER option set, adjacencies in entities in <em>entities</em> are updated.
1708  \param meshset Mesh set being removed from
1709  \param entities 1d vector of entities being removed from meshset
1710  \param num_entities Number of entities in 1d vector
1711  */
1712  virtual ErrorCode remove_entities( EntityHandle meshset, const EntityHandle* entities, const int num_entities ) = 0;
1713 
1714  //! Return whether a set contains entities
1715  /** Return whether a set contains entities. Returns true only
1716  * if ALL entities are contained
1717  * \param meshset Mesh set being queried
1718  * \param entities Entities being queried
1719  * \param num_entities Number of entities
1720  * \return bool If true, all entities are contained in set
1721  */
1722  virtual bool contains_entities( EntityHandle meshset,
1723  const EntityHandle* entities,
1724  int num_entities,
1725  const int operation_type = Interface::INTERSECT ) = 0;
1726 
1727  //! Replace entities in a set with other entities
1728  /** Replace entities in a set with other entities
1729  *
1730  * \note Behavior is undefined if an entity handle exists in both the
1731  * old_entities and the new_entities arrays or old_entities
1732  * contains multiple copies of an entity.
1733  * \note If an entity occurs multiple times in an ordered set, all
1734  * occurances will be replaced.
1735  * \note For list-based sets, if not all handles in old_entities
1736  * occcur in the set, the corresponding new_entities will not
1737  * be added and MB_ENTITY_NOT_FOUND will be returned.
1738  * For set-based sets, all entities in new_entities wll be
1739  * added and any contained entities in old_entities will be
1740  * removed, and the return value will be MB_SUCCESS.
1741  * \param meshset Mesh set being modified
1742  * \param old_entities Entities to replace
1743  * \param new_entities New entities to add
1744  * \param num_entities Number of entities in input arrays
1745  * \return - MB_SUCCESS : all entities in old_entities replaced
1746  * - MB_ENTITY_NOT_FOUND : one or more entities in new_entities
1747  * not added to set because corresponding entity
1748  * in old_entities did not occur in the ordered
1749  * set.
1750  * - MB_FAILURE : internal error
1751  */
1752  virtual ErrorCode replace_entities( EntityHandle meshset,
1753  const EntityHandle* old_entities,
1754  const EntityHandle* new_entities,
1755  int num_entities ) = 0;
1756  /**@}*/
1757 
1758  /** \name Set parents/children */
1759 
1760  /**@{*/
1761 
1762  //! Get parent mesh sets of a mesh set
1763  /** If <em>num_hops</em> is 1, only immediate parents are returned. If <em>num_hops</em> is
1764  zero, all ancenstors are returned. Otherwise, <em>num_hops</em> specifies the maximum number
1765  of generations to traverse. \param meshset The mesh set whose parents are being queried
1766  \param parents STL vector holding the parents returned by this function
1767  \param num_hops Number of generations to traverse (0 = all)
1768  */
1769  virtual ErrorCode get_parent_meshsets( const EntityHandle meshset,
1770  std::vector< EntityHandle >& parents,
1771  const int num_hops = 1 ) const = 0;
1772 
1773  //! Get parent mesh sets of a mesh set
1774  /** If <em>num_hops</em> is 1, only immediate parents are returned. If <em>num_hops</em> is
1775  zero, all ancenstors are returned. Otherwise, <em>num_hops</em> specifies the maximum number
1776  of generations to traverse. \param meshset The mesh set whose parents are being queried
1777  \param parents Range holding the parents returned by this function
1778  \param num_hops Number of generations to traverse (0 = all)
1779  */
1780  virtual ErrorCode get_parent_meshsets( const EntityHandle meshset,
1781  Range& parents,
1782  const int num_hops = 1 ) const = 0;
1783 
1784  //! Get child mesh sets of a mesh set
1785  /** If <em>num_hops</em> is 1, only immediate children are returned. If <em>num_hops</em> is
1786  zero, all ancenstors are returned. Otherwise, <em>num_hops</em> specifies the maximum number
1787  of generations to traverse. \param meshset The mesh set whose children are being queried
1788  \param children STL vector holding the children returned by this function
1789  \param num_hops Number of generations to traverse (0 = all)
1790  */
1791  virtual ErrorCode get_child_meshsets( const EntityHandle meshset,
1792  std::vector< EntityHandle >& children,
1793  const int num_hops = 1 ) const = 0;
1794 
1795  //! Get child mesh sets of a mesh set
1796  /** If <em>num_hops</em> is 1, only immediate children are returned. If <em>num_hops</em> is
1797  zero, all ancenstors are returned. Otherwise, <em>num_hops</em> specifies the maximum number
1798  of generations to traverse. \param meshset The mesh set whose children are being queried
1799  \param children Range holding the children returned by this function
1800  \param num_hops Number of generations to traverse (0 = all)
1801  */
1802  virtual ErrorCode get_child_meshsets( const EntityHandle meshset,
1803  Range& children,
1804  const int num_hops = 1 ) const = 0;
1805 
1806  /**\brief Get mesh sets contained in a mesh set
1807  *
1808  * If <em>num_hops</em> is 1, only immediate contents are returned.
1809  * Otherwise a recursive query of all contained sets is performed,
1810  * returning every visted set. The value of num_hops limites the
1811  * depth of the search, with zero indicating no depth limit.
1812  *
1813  *\param meshset The mesh set whose contents are being queried
1814  *\param contained The result list.
1815  *\param num_hops Number of generations to traverse (0 = all)
1816  */
1817  virtual ErrorCode get_contained_meshsets( const EntityHandle meshset,
1818  std::vector< EntityHandle >& contained,
1819  const int num_hops = 1 ) const = 0;
1820 
1821  /**\brief Get mesh sets contained in a mesh set
1822  *
1823  * If <em>num_hops</em> is 1, only immediate contents are returned.
1824  * Otherwise a recursive query of all contained sets is performed,
1825  * returning every visted set. The value of num_hops limites the
1826  * depth of the search, with zero indicating no depth limit.
1827  *
1828  *\param meshset The mesh set whose contents are being queried
1829  *\param contained The result list.
1830  *\param num_hops Number of generations to traverse (0 = all)
1831  */
1832  virtual ErrorCode get_contained_meshsets( const EntityHandle meshset,
1833  Range& contained,
1834  const int num_hops = 1 ) const = 0;
1835 
1836  //! Get the number of parent mesh sets of a mesh set
1837  /** Identical to get_parent_meshsets, only number is returned instead of actual parents.
1838  \param meshset The mesh set whose parents are being queried
1839  \param number Number of parents
1840  */
1841  virtual ErrorCode num_parent_meshsets( const EntityHandle meshset, int* number, const int num_hops = 1 ) const = 0;
1842 
1843  //! Get the number of child mesh sets of a mesh set
1844  /** Identical to get_child_meshsets, only number is returned instead of actual children.
1845  \param meshset The mesh set whose children are being queried
1846  \param number Number of children
1847  */
1848  virtual ErrorCode num_child_meshsets( const EntityHandle meshset, int* number, const int num_hops = 1 ) const = 0;
1849 
1850  /**\brief Get the number of mesh sets contained in a mesh set
1851  *
1852  * Return the number of sets that would be returned by get_contained_meshsets
1853  *
1854  *\param meshset The initial set to begin the query from.
1855  *\param number (Output) The result count.
1856  *\param num_hops Search depth (0 => unbounded).
1857  */
1858  virtual ErrorCode num_contained_meshsets( const EntityHandle meshset,
1859  int* number,
1860  const int num_hops = 1 ) const = 0;
1861 
1862  //! Add a parent mesh set to a mesh set
1863  /** Make <em>parent_meshset</em> a new parent of <em>child_meshset</em>. This function does
1864  <em>not</em> add a corresponding child link to <em>parent_meshset</em>.
1865  \param child_meshset The child mesh set being given a new parent.
1866  \param parent_meshset The parent being added to <em>child_meshset</em>
1867  */
1868  virtual ErrorCode add_parent_meshset( EntityHandle child_meshset, const EntityHandle parent_meshset ) = 0;
1869 
1870  //! Add a parent mesh sets to a mesh set
1871  /** Make <em>parent_meshset</em> a new parent of <em>child_meshset</em>. This function does
1872  <em>not</em> add a corresponding child link to <em>parent_meshset</em>.
1873  \param child_meshset The child mesh set being given a new parent.
1874  \param parent_meshset The parent being added to <em>child_meshset</em>
1875  */
1876  virtual ErrorCode add_parent_meshsets( EntityHandle child_meshset,
1877  const EntityHandle* parent_meshsets,
1878  int num_parent_meshsets ) = 0;
1879 
1880  //! Add a child mesh set to a mesh set
1881  /** Make <em>child_meshset</em> a new child of <em>parent_meshset</em>. This function does
1882  <em>not</em> add a corresponding parent link to <em>child_meshset</em>.
1883  \param parent_meshset The parent mesh set being given a new child.
1884  \param child_meshset The child being added to <em>parent_meshset</em>
1885  */
1886  virtual ErrorCode add_child_meshset( EntityHandle parent_meshset, const EntityHandle child_meshset ) = 0;
1887 
1888  //! Add a child mesh sets to a mesh set
1889  /** Make <em>child_meshset</em> a new child of <em>parent_meshset</em>. This function does
1890  <em>not</em> add a corresponding parent link to <em>child_meshset</em>.
1891  \param parent_meshset The parent mesh set being given a new child.
1892  \param child_meshset The child being added to <em>parent_meshset</em>
1893  */
1894  virtual ErrorCode add_child_meshsets( EntityHandle parent_meshset,
1895  const EntityHandle* child_meshsets,
1896  int num_child_meshsets ) = 0;
1897 
1898  //! Add parent and child links between mesh sets
1899  /** Makes <em>child_meshset</em> a new child of <em>parent_meshset</em>, and vica versa.
1900  \param parent The parent mesh set being given a new child, and the new parent
1901  \param child The child being given a new parent, and the new child
1902  */
1903  virtual ErrorCode add_parent_child( EntityHandle parent, EntityHandle child ) = 0;
1904 
1905  //! Remove parent and child links between mesh sets
1906  /** Removes parent/child links between <em>child_meshset</em> and <em>parent_meshset</em>.
1907  \param parent The parent mesh set being removed from <em>child</em>
1908  \param child The child mesh set being removed from <em>parent</em>
1909  */
1910  virtual ErrorCode remove_parent_child( EntityHandle parent, EntityHandle child ) = 0;
1911 
1912  //! Remove a parent mesh set from a mesh set
1913  /** Removes <em>parent_meshset</em> from the parents of <em>child_meshset</em>. This function
1914  does <em>not</em> remove a corresponding child link from <em>parent_meshset</em>. \param
1915  child_meshset The child mesh whose parent is being removed \param parent_meshset The parent
1916  being removed from <em>meshset</em>
1917  */
1918  virtual ErrorCode remove_parent_meshset( EntityHandle child_meshset, const EntityHandle parent_meshset ) = 0;
1919 
1920  //! Remove a child mesh set from a mesh set
1921  /** Removes <em>child_meshset</em> from the children of <em>parent_meshset</em>. This function
1922  does <em>not</em> remove a corresponding parent link from <em>child_meshset</em>. \param
1923  parent_meshset The parent mesh set whose child is being removed \param child_meshset The
1924  child being removed from <em>parent_meshset</em>
1925  */
1926  virtual ErrorCode remove_child_meshset( EntityHandle parent_meshset, const EntityHandle child_meshset ) = 0;
1927 
1928  // ! Returns the global id tag; default value is -1
1929  virtual Tag globalId_tag() = 0;
1930 
1931  /**@}*/
1932 
1933  /** \name Set iterators */
1934 
1935  /**@{*/
1936 
1937  /** \brief Create an iterator over the set
1938  * Create a new iterator that iterates over entities with the specified type or dimension.
1939  * Only one of ent_type or dim can be set; use dim=-1 or ent_type=MBMAXTYPE for the other.
1940  * Iterators for list-type (ordered) sets are stable over set modification, unless entity
1941  * removed or deleted is the one at the current position of the iterator. If the check_valid
1942  * parameter is passed as true, entities are checked for validity before being passed back by
1943  * get_next_entities function (checking entity validity can have a non-negligible cost).
1944  *
1945  * Iterators returned by this function can be deleted using the normal C++ delete function.
1946  * After creating the iterator through this function, further interactions are through methods
1947  * on the SetIterator class.
1948  * \param meshset The entity set associated with this iterator (use 0 for whole instance)
1949  * \param ent_type Entity type associated with this iterator
1950  * \param ent_dim Dimension associated with this iterator
1951  * \param chunk_size Chunk size of the iterator
1952  * \param check_valid If true, entities are checked for validity before being returned
1953  */
1954 
1955  virtual ErrorCode create_set_iterator( EntityHandle meshset,
1956  EntityType ent_type,
1957  int ent_dim,
1958  int chunk_size,
1959  bool check_valid,
1960  SetIterator*& set_iter ) = 0;
1961  /**@}*/
1962 
1963  // ************************ Interface options controllable by user ***************
1964 
1965  /** \name Sequence Option controllers */
1966 
1967  /**@{*/
1968 
1969  /** \brief Interface to control memory allocation for sequences
1970  * Provide a factor that controls the size of the sequence that gets allocated.
1971  * This is typically useful in the parallel setting when a-priori, the number of ghost entities
1972  * and the memory required for them within the same sequence as the owned entities are unknown.
1973  * The default factor is 1.0 but this can be appropriately updated at runtime so that we do not
1974  * have broken sequences.
1975  */
1976  virtual double get_sequence_multiplier() const = 0;
1977 
1978  /** \brief Interface to control memory allocation for sequences
1979  * Provide a factor that controls the size of the sequence that gets allocated.
1980  * This is typically useful in the parallel setting when a-priori, the number of ghost entities
1981  * and the memory required for them within the same sequence as the owned entities are unknown.
1982  * The default factor is 1.0 but this can be appropriately updated at runtime so that we do not
1983  * have broken sequences.
1984  *
1985  * \param meshset User specified multiplier (should be greater than 1.0)
1986  */
1987  virtual void set_sequence_multiplier( double factor ) = 0;
1988 
1989  /**@}*/
1990 };
1991 
1992 //! predicate for STL algorithms. Returns true if the entity handle is
1993 //! of the specified type. For example, to remove all the tris out of a list
1994 //! of 2D entities retrieved using get_adjacencies you could do
1995 //! std::remove_if(list.begin(), list.end(), type_equals(gMB, MBTRI));
1996 class type_equals
1997 {
1998  // deprecation of unary_function
1999  typedef EntityHandle argument_type;
2000  typedef bool result_type;
2001 
2002  public:
2003  //! interface object
2004  Interface* meshDB;
2005 
2006  //! type corresponding to this predicate
2007  const EntityType test_type;
2008 
2009  //! Constructor
2010  type_equals( Interface* mdb, const EntityType type ) : meshDB( mdb ), test_type( type ) {}
2011 
2012  //! operator predicate
2013  bool operator()( EntityHandle handle ) const
2014  {
2015  return ( meshDB->type_from_handle( handle ) == test_type );
2016  }
2017 };
2018 
2019 //! predicate for STL algorithms. Returns true if the entity handle is not
2020 //! of the specified type. For example, to remove all but the tris out of a list
2021 //! of 2D entities retrieved using get_adjacencies you could do
2022 //! std::remove_if(list.begin(), list.end(), type_not_equals(gMB, MBTRI));
2023 class type_not_equals
2024 {
2025  // deprecation of unary_function
2026  typedef EntityHandle argument_type;
2027  typedef bool result_type;
2028 
2029  public:
2030  //! interface object
2031  Interface* meshDB;
2032 
2033  //! type corresponding to this predicate
2034  const EntityType test_type;
2035 
2036  //! Constructor
2037  type_not_equals( Interface* mdb, const EntityType type ) : meshDB( mdb ), test_type( type ) {}
2038 
2039  //! operator predicate
2040  bool operator()( EntityHandle handle ) const
2041  {
2042  return ( meshDB->type_from_handle( handle ) != test_type );
2043  }
2044 };
2045 
2046 inline float Interface::api_version( std::string* version_string )
2047 {
2048  if( NULL != version_string )
2049  *version_string = std::string( "MOAB API version " ) + std::string( MOAB_API_VERSION_STRING );
2050  return MOAB_API_VERSION;
2051 }
2052 
2053 } // namespace moab
2054 
2055 #endif // MB_INTERFACE_HPP