DAGMC Interface

struct DagmcVolData

Public Members

int mat_id

double density

double importance

std::string comp_name

namespace moab

class DagMC

#include <DagMC.hpp>

In section 1, the public interface you will find all the functions needed for problem setup. For the typical MC code, the order of function calls required to fully populate DAGMC ready to run are.

1) DAG->load_file(); 2) DAG->init_OBBTree();

Modifications were made to init_OBBTree which allows the functions of init_OBBTree to be called without having used init_OBBTree. For example if you would like access to be able to call DAG->point_in_volume() but without having an implicit compliment you need only call

1) DAG->load_file(); 2) DAG->setup_obb();

Similarly, if you need access to problem indices only, one may call load_file followed by setup_indices.

1) DAG->load_file(); 2) DAG->setup_indices();

Public Types

typedef GeomQueryTool::RayHistory RayHistory

The methods in this section are thin wrappers around methods in the GeometryQueryTool.

Public Functions

DagMC(

std::shared_ptr<Interface> mb_impl = nullptr,

double overlap_tolerance = 0.,

double numerical_precision = .001,

int verbosity = 1,

)

DagMC(

Interface *mb_impl,

double overlap_tolerance = 0.,

double numerical_precision = .001,

int verbosity = 1,

)

~DagMC()

inline std::string git_sha()

Git revision of DAGMC

ErrorCode load_file(const char *cfile)

Load a geometry description regardless of format.

This method will load the geometry file with name cfile. In case this is a solid model geometry file, it will pass the facet_tolerance option as guidance for the faceting engine.

Note: When loading a prexisting file with an OBB_TREE tag, a number of unspoken things happen that one should be aware of.

1) The file is loaded and when we query the meshset, we find entities with the OBB_TREE tag 2) The OBBTreeTool assumes that any children of the entity being queried in a ray intersect sets operation are fair game, the surface meshsets have triangles as members, but OBBs as children but no querying is done, just assumptions that the tags exist.

Parameters:

• cfile -- the file name to be loaded

• facet_tolerance -- the faceting tolerance guidance for the faceting engine

Returns:

- MB_SUCCESS if file loads correctly

• other MB ErrorCodes returned from MOAB

ErrorCode load_existing_contents()

ErrorCode init_OBBTree()

initializes the geometry and OBB tree structure for ray firing acceleration

This method can be called after load_file to fully initialize DAGMC. It calls methods to set up the geometry, create the implicit complement, generate an OBB tree from the faceted representation of the geometry, and build the cross-referencing indices.

ErrorCode setup_impl_compl()

finds or creates the implicit complement

This method calls the GeomTopoTool->get_implicit_complement which will return the IC if it already exists. If the IC doesn't exist, it will create one.

ErrorCode setup_geometry(Range &surfs, Range &vols)

sets up ranges of the volume and surface entity sets

Helper function for setup_indices. Sets ranges containing all volumes and surfaces.

ErrorCode setup_obbs()

constructs obb trees for all surfaces and volumes

Very thin wrapper around GTT->construct_obb_trees(). Constructs obb trees for all surfaces and volumes in the geometry.

ErrorCode setup_indices()

thin wrapper around build_indices()

Very thin wrapper around build_indices().

ErrorCode remove_graveyard()

Removes the graveyard if one is present.

ErrorCode create_graveyard(bool overwrite = false)

Create a graveyard (a volume representing the volume boundary).

Create a cuboid volume marked with metadata indicating it is the boundary of the DAGMC model. This method will fail if a graveyard volume already exists and overwrite is not true. Requires BVH tree's existence.

bool has_graveyard()

Returns true if the model has a graveyard volume, false if not

bool has_acceleration_datastructures()

Returns true if the model has any trees, false if not

ErrorCode get_graveyard_group(EntityHandle &graveyard_group)

Retrieve the graveyard group on the model if it exists

ErrorCode ray_fire(

const EntityHandle volume,

const double ray_start[3],

const double ray_dir[3],

EntityHandle &next_surf,

double &next_surf_dist,

RayHistory *history = NULL,

double dist_limit = 0,

int ray_orientation = 1,

OrientedBoxTreeTool::TrvStats *stats = NULL,

)

Fires a ray from a starting point in a given direction and returns the next surface hit.

Parameters:

• volume -- The volume within which the ray is fired.

• ray_start -- A 3-element array representing the starting point of the ray.

• ray_dir -- A 3-element array representing the unit direction of the ray.

• next_surf -- [out] The handle of the next surface hit by the ray.

• next_surf_dist -- [out] The distance from the ray start to the next surface.

• history -- Optional. A pointer to a RayHistory object for storing the ray's path.

• dist_limit -- Optional. The maximum distance the ray should travel. Default is 0, which means no limit.

• ray_orientation -- Optional. The orientation triangle normals considered valid for a hit.Default is 1 (forward).

• stats -- Optional. A pointer to a TrvStats object for storing traversal statistics of the ray. Default is NULL.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode point_in_volume(

const EntityHandle volume,

const double xyz[3],

int &result,

const double *uvw = NULL,

const RayHistory *history = NULL,

)

Determines whether a given point is inside a specified volume.

Parameters:

• volume -- The volume within which the point is being tested.

• xyz -- A 3-element array representing the coordinates of the point.

• result -- [out] The result of the operation. It will be set to 1 if the point is inside the volume and 0 if it is outside.

• uvw -- Optional. A 3-element array representing the unit direction from the point to the volume. Default is NULL. A randomly generated direction will be used if not provided.

• history -- Optional. A pointer to a RayHistory object for masking out previously hit triangles. Default is NULL.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode point_in_volume_slow(

const EntityHandle volume,

const double xyz[3],

int &result,

)

Determines whether a given point is inside a specified volume. This function is slower than point_in_volume.

This method is adapted from "Point in Polyhedron Testing Using Spherical

Polygons", Paulo Cezar Pinto Carvalho and Paulo Roma Cavalcanti,

Graphics Gems V

, pg. 42. The original algorithm was described in "An Efficient

Point In Polyhedron Algorithm", Jeff Lane, Bob Magedson, and Mike Rarick,

Computer Vision, Graphics, and Image Processing 26, pg. 118-225, 1984.

Parameters:

• volume -- The volume within which the point is being tested.

• xyz -- A 3-element array representing the coordinates of the point.

• result -- [out] The result of the operation. It will be set to 1 if the point is inside the volume and 0 if it is outside.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode test_volume_boundary(

const EntityHandle volume,

const EntityHandle surface,

const double xyz[3],

const double uvw[3],

int &result,

const RayHistory *history = NULL,

)

Given a ray starting at a surface of a volume, check whether the ray enters or exits the volume.

This function is most useful for rays that change directions at a surface crossing. It can be used to check whether a direction change redirects the ray back into the originating volume.

Parameters:

• volume -- The volume to be tested.

• surface -- The surface to be tested.

• xyz -- A 3-element array representing the coordinates of the point.

• uvw -- A 3-element array representing the unit direction from the point to the volume.

• result -- [out] The result of the operation. Set to 1 if ray is entering volume, or 0 if it is leaving.

• history -- If present and non-empty, the history is used to look up the surface facet at which the ray begins. Absent a history, the facet nearest to xyz will be looked up. The history should always be provided if available, as it avoids the computational expense of a nearest-facet query. Default is NULL.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode closest_to_location(

EntityHandle volume,

const double point[3],

double &result,

EntityHandle *surface = 0,

)

Finds the point in a specified volume that is closest to a given location.

Parameters:

• volume -- The volume to be searched.

• point -- A 3-element array representing the coordinates of the location.

• result -- [out] The distance from the location to the closest point in the volume.

• surface -- [out] Optional. The handle of the surface on which the closest point lies. Default is 0.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode measure_volume(EntityHandle volume, double &result)

Measures the volume of a specified volume.

Parameters:

• volume -- The volume to be measured.

• result -- [out] The measured volume.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode measure_area(EntityHandle surface, double &result)

Measures the area of a specified surface.

Parameters:

• surface -- The surface to be measured.

• result -- [out] The measured area.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode surface_sense(

EntityHandle volume,

int num_surfaces,

const EntityHandle *surfaces,

int *senses_out,

)

Determines the sense of one or more surfaces with respect to a specified volume.

This method assumes that the surfaces passed in are part of the volume.

Parameters:

• volume -- The volume with respect to which the sense is determined.

• num_surfaces -- The number of surfaces for which to determine the sense.

• surfaces -- An array of handles of the surfaces for which to determine the sense.

• senses_out -- [out] An array in which to store the determined senses.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode surface_sense(

EntityHandle volume,

EntityHandle surface,

int &sense_out,

)

Determines the sense of a surface with respect to a specified volume.

This method assumes that the surface passed in is part of the volume.

Parameters:

• volume -- The volume with respect to which the sense is determined.

• surface -- The handle of the surface for which to determine the sense.

• sense_out -- [out] The determined sense.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode get_angle(

EntityHandle surf,

const double xyz[3],

double angle[3],

const RayHistory *history = NULL,

)

Returns the normal vector of a surface at the specified point. from the ray origin in a specified direction. It is assumed that the specified point is on the surface.

This method first identifies which triangle contains this point and then calculates the unit outward normal of that triangle. The triangle of the provided volume that is nearest the provided point is used for this calculation. The search for that triangle can be circumvented by providing a RayHistory, in which case the last triangle of the history will be used.

Parameters:

• surf -- The surface for which a normal vector is determined.

• xyz -- A 3-element array representing the coordinates of the point.

• angle[out] -- A 3-element array in which to store the determined surface normal.

• history -- Optional. A pointer to a RayHistory object storing previously hit triangles. Default is NULL.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

ErrorCode next_vol(

EntityHandle surface,

EntityHandle old_volume,

EntityHandle &new_volume,

)

Finds the volume adjacent to a specified surface and volume.

Parameters:

• surface -- The surface across which to find the adjacent volume.

• old_volume -- The volume from which to find the adjacent volume.

• new_volume -- [out] The handle of the adjacent volume.

Returns:

Returns an ErrorCode indicating the success or failure of the operation.

EntityHandle entity_by_id(int dimension, int id) const

Most calling apps refer to geometric entities with a combination of base-1/0 ordinal index (or rank) and global ID (or name). DagMC also has an internal EntityHandle reference to each geometric entity. These method provide ways to translate from one to the other. map from dimension & global ID to EntityHandle

inline EntityHandle entity_by_index(int dimension, int index) const

map from dimension & base-1 ordinal index to EntityHandle

int id_by_index(int dimension, int index) const

map from dimension & base-1 ordinal index to global ID

inline int index_by_handle(EntityHandle handle) const

PPHW: Missing dim & global ID ==> base-1 ordinal index map from EntityHandle to base-1 ordinal index

int get_entity_id(EntityHandle this_ent) const

map from EntityHandle to global ID

inline unsigned int num_entities(int dimension) const

get number of geometric sets corresponding to geometry of specified dimension

For a given dimension (e.g. dimension=3 for volumes, dimension=2 for surfaces) return the number of entities of that dimension

Parameters:

dimension -- the dimensionality of the entities in question

Returns:

integer number of entities of that dimension

double overlap_thickness()

retrieve overlap thickness

double numerical_precision()

retrieve numerical precision

inline double faceting_tolerance()

retrieve faceting tolerance

void set_overlap_thickness(double new_overlap_thickness)

Attempt to set a new overlap thickness tolerance, first checking for sanity

void set_numerical_precision(double new_precision)

Attempt to set a new numerical precision , first checking for sanity Use of this function is discouraged; see top of DagMC.cpp

ErrorCode detect_available_props(

std::vector<std::string> &keywords_out,

const char *delimiters = "_",

)

Detect all the property keywords that appear in the loaded geometry

Parameters:

keywords_out -- The result list of keywords. This list could be validly passed to parse_properties().

ErrorCode parse_properties(

const std::vector<std::string> &keywords,

const std::map<std::string, std::string> &synonyms = no_synonyms,

const char *delimiters = "_",

)

Parse properties from group names per metadata syntax standard

Parameters:

• keywords -- A list of keywords to parse. These are considered the canonical names of the properties, and constitute the valid inputs to has_prop() and prop_value().

• delimiters -- An array of characters the routine will use to split the groupname into properties.

• synonyms -- An optional mapping of synonym keywords to canonical keywords. This allows more than one group name keyword to take on the same meaning e.g. if synonyms["rest.of.world"] = "graveyard", then volumes in the "rest.of.world" group will behave as if they were in a group named "graveyard".

ErrorCode prop_value(

EntityHandle eh,

const std::string &prop,

std::string &value,

)

Get the value of a property on a volume or surface

Parameters:

• eh -- The entity handle to get a property value on

• prop -- The canonical property name

• value -- Output parameter, the value of the property. If no value was set on the handle, this will be the empty string.

Returns:

MB_TAG_NOT_FOUND if prop is invalid. Otherwise return any errors from MOAB, or MB_SUCCESS if successful

ErrorCode prop_values(

EntityHandle eh,

const std::string &prop,

std::vector<std::string> &value,

)

Get the value of a property on a volume or surface

Parameters:

• eh -- The entity handle to get a property value on

• prop -- The canonical property name

• values -- Output parameter, the values of the property will be appended to this list. If no value was set on the handle, no entries will be added.

Returns:

MB_TAG_NOT_FOUND if prop is invalid. Otherwise return any errors from MOAB, or MB_SUCCESS if successful

bool has_prop(EntityHandle eh, const std::string &prop)

Return true if a volume or surface has the named property set upon it

Parameters:

• eh -- The entity handle to query

• prop -- The canonical property name @retrun True if the handle has the property set, or false if not. False is also returned if a MOAB error occurs.

ErrorCode get_all_prop_values(

const std::string &prop,

std::vector<std::string> &return_list,

)

Get a list of all unique values assigned to a named property on any entity

Parameters:

• prop -- The canonical property name

• return_list -- Output param, a list of unique strings that are set as values for this property

Returns:

MB_TAG_NOT_FOUND if prop is invalid. Otherwise return any errors from MOAB, or MB_SUCCESS if succesful

ErrorCode entities_by_property(

const std::string &prop,

std::vector<EntityHandle> &return_list,

int dimension = 0,

const std::string *value = NULL,

)

Get a list of all entities which have a given property

Parameters:

• prop -- The canonical property name

• return_list -- Output param, a list of entity handles that have this property

• dimension -- If nonzero, entities returned will be restricted to the given dimension, i.e. 2 for surfaces and 3 for volumes @parm value If non-NULL, only entities for which the property takes on this value will be returned.

Returns:

MB_TAG_NOT_FOUND if prop is invalid. Otherwise return any errors from MOAB, or MB_SUCCESS if successful

bool is_implicit_complement(EntityHandle volume)

Checks if a given volume is the implicit complement.

Parameters:

volume -- The volume to be checked.

Returns:

Returns true if the volume is the implicit complement, false otherwise.

inline Tag name_tag()

get the tag for the "name" of a surface == global ID

inline Tag obb_tag()

Get the tag used to associate OBB trees with geometry in load_file(..). not sure what to do about the obb_tag, GTT has no concept of an obb_tag on EntitySets - PCS

Tag category_tag()

inline Tag geom_tag()

inline Tag id_tag()

inline Tag sense_tag()

inline OrientedBoxTreeTool *obb_tree()

inline std::shared_ptr<GeomTopoTool> geom_tool()

ErrorCode write_mesh(const char *ffile, const int flen)

ErrorCode getobb(EntityHandle volume, double minPt[3], double maxPt[3])

get the corners of the OBB for a given volume

ErrorCode getobb(

EntityHandle volume,

double center[3],

double axis1[3],

double axis2[3],

double axis3[3],

)

get the center point and three vectors for the OBB of a given volume

inline ErrorCode get_root(EntityHandle vol_or_surf, EntityHandle &root)

get the root of the obbtree for a given entity

inline Interface *moab_instance()

Get the instance of MOAB used by functions in this file.

inline std::shared_ptr<Interface> moab_instance_sptr()

Public Members

Tag nameTag

Tag facetingTolTag

Public Static Functions

static float version(std::string *version_string = NULL)

Return the version of this library

static inline unsigned int interface_revision()

Get subversion revision of this file (DagMC.hpp)

Private Types

typedef std::map<std::string, std::string> prop_map

a common type within the property and group name functions

using RayTracer = GeomQueryTool

Private Functions

ErrorCode box_to_surf(

const double llc[3],

const double urc[3],

EntityHandle &surface_set,

)

convenience function for converting a bounding box into a box of triangles with outward facing normals and setting up set structure necessary for representation as a geometric entity

ErrorCode remove_bvh(EntityHandle volume, bool unjoin_vol = false)

Removes the BVH for the specified volume.

ErrorCode build_bvh(EntityHandle volume)

Builds the BVH for a specified volume.

ErrorCode finish_loading()

loading code shared by load_file and load_existing_contents

ErrorCode get_groups(Range &groups)

get all group sets on the model

ErrorCode build_indices(Range &surfs, Range &vols)

build internal index vectors that speed up handle-by-id, etc.

void tokenize(

const std::string &str,

std::vector<std::string> &tokens,

const char *delimiters = "_",

) const

tokenize the metadata stored in group names

ErrorCode get_group_name(EntityHandle group_set, std::string &name)

Store the name of a group in a string

ErrorCode parse_group_name(

EntityHandle group_set,

prop_map &result,

const char *delimiters = "_",

)

Parse a group name into a set of key:value pairs

ErrorCode append_packed_string(Tag, EntityHandle, std::string&)

Add a string value to a property tag for a given entity

ErrorCode unpack_packed_string(

Tag tag,

EntityHandle eh,

std::vector<std::string> &values,

)

Convert a property tag's value on a handle to a list of strings

inline std::vector<EntityHandle> &surf_handles()

inline std::vector<EntityHandle> &vol_handles()

inline std::vector<EntityHandle> &group_handles()

Tag get_tag(

const char *name,

int size,

TagType store,

DataType type,

const void *def_value = NULL,

bool create_if_missing = true,

)

Private Members

std::shared_ptr<Interface> MBI_shared_ptr

Interface *MBI

bool moab_instance_created

std::shared_ptr<GeomTopoTool> GTT

std::unique_ptr<RayTracer> ray_tracer

std::vector<EntityHandle> entHandles[5]

store some lists indexed by handle

std::unordered_map<EntityHandle, int> entIndices

surface and volume mapping from EntitiyHandle to DAGMC index

std::vector<RefEntity*> geomEntities

corresponding geometric entities; also indexed like rootSets

std::map<std::string, Tag> property_tagmap

map from the canonical property names to the tags representing them

char implComplName[NAME_TAG_SIZE]

double facetingTolerance

std::vector<double> disList

vectors for point_in_volume:

std::vector<int> dirList

std::vector<EntityHandle> surList

std::vector<EntityHandle> facList

DagMC_Logger logger

logger

Private Static Attributes

static const std::map<std::string, std::string> no_synonyms

empty synonym map to provide as a default argument to parse_properties()

struct BBOX

Public Functions

inline bool valid()

ensure box corners are valid

inline void update(double x, double y, double z)

update box to ensure the provided point is contained

inline void expand(double bump)

expand the box by some absolute value

inline void update(double xyz[3])

update box to ensure the provided point is contained

Public Members

double lower[3] = {INFTY, INFTY, INFTY}

double upper[3] = {-INFTY, -INFTY, -INFTY}

Public Static Attributes

static constexpr double INFTY = {std::numeric_limits<double>::max()}