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