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