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