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