diff --git a/src/dagmc/DagMC.hpp b/src/dagmc/DagMC.hpp index 09afe6b0d..affb71dbe 100644 --- a/src/dagmc/DagMC.hpp +++ b/src/dagmc/DagMC.hpp @@ -212,200 +212,215 @@ class DagMC { typedef GeomQueryTool::RayHistory RayHistory; - /** - * @brief Fires a ray from a starting point in a given direction and returns the next surface hit. - * - * @param volume The volume within which the ray is fired. - * @param ray_start A 3-element array representing the starting point of the ray. - * @param ray_dir A 3-element array representing the unit direction of the ray. - * @param[out] next_surf The handle of the next surface hit by the ray. - * @param[out] next_surf_dist The distance from the ray start to the next surface. - * @param history Optional. A pointer to a RayHistory object for storing the ray's path. - * @param dist_limit Optional. The maximum distance the ray should travel. Default is 0, which means no limit. - * @param ray_orientation Optional. The orientation triangle normals considered valid for a hit.Default is 1 (forward). - * @param stats Optional. A pointer to a TrvStats object for storing traversal statistics of the ray. Default is NULL. - * - * @return Returns an ErrorCode indicating the success or failure of the operation. - */ - 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, + * @brief Fires a ray from a starting point in a given direction and returns + * the next surface hit. + * + * @param volume The volume within which the ray is fired. + * @param ray_start A 3-element array representing the starting point of the + * ray. + * @param ray_dir A 3-element array representing the unit direction of the + * ray. + * @param[out] next_surf The handle of the next surface hit by the ray. + * @param[out] next_surf_dist The distance from the ray start to the next + * surface. + * @param history Optional. A pointer to a RayHistory object for storing the + * ray's path. + * @param dist_limit Optional. The maximum distance the ray should travel. + * Default is 0, which means no limit. + * @param ray_orientation Optional. The orientation triangle normals + * considered valid for a hit.Default is 1 (forward). + * @param stats Optional. A pointer to a TrvStats object for storing traversal + * statistics of the ray. Default is NULL. + * + * @return Returns an ErrorCode indicating the success or failure of the + * operation. + */ + 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); - /** - * @brief Determines whether a given point is inside a specified volume. - * - * @param volume The volume within which the point is being tested. - * @param xyz A 3-element array representing the coordinates of the point. - * @param[out] result The result of the operation. It will be set to 1 if the - * point is inside the volume and 0 if it is outside. - * @param 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. - * @param history Optional. A pointer to a RayHistory object for masking out previously hit triangles. Default is NULL. - * - * @return 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, + * @brief Determines whether a given point is inside a specified volume. + * + * @param volume The volume within which the point is being tested. + * @param xyz A 3-element array representing the coordinates of the point. + * @param[out] result The result of the operation. It will be set to 1 if the + * point is inside the volume and 0 if it is outside. + * @param 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. + * @param history Optional. A pointer to a RayHistory object for masking out + * previously hit triangles. Default is NULL. + * + * @return 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); /** - * @brief Determines whether a given point is inside a specified volume. This function is slower than point_in_volume. - * - * @param volume The volume within which the point is being tested. - * @param xyz A 3-element array representing the coordinates of the point. - * @param[out] result The result of the operation. It will be set to 1 if the point is inside the volume and 0 if it is outside. - * - * @return Returns an ErrorCode indicating the success or failure of the operation. - */ - ErrorCode point_in_volume_slow(const EntityHandle volume, - const double xyz[3], + * @brief Determines whether a given point is inside a specified volume. This + * function is slower than point_in_volume. + * + * @param volume The volume within which the point is being tested. + * @param xyz A 3-element array representing the coordinates of the point. + * @param[out] result The result of the operation. It will be set to 1 if the + * point is inside the volume and 0 if it is outside. + * + * @return 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); #if MOAB_VERSION_MAJOR == 5 && MOAB_VERSION_MINOR > 2 /** - * @brief Finds the volume containing a given point. - * - * @param xyz A 3-element array representing the coordinates of the point. - * @param[out] volume The volume containing the point. - * @param uvw Optional. A 3-element array representing the unit direction to be used when firing a test ray. Default is NULL. - * - * @return Returns an ErrorCode indicating the success or failure of the operation. - */ - ErrorCode find_volume(const double xyz[3], - EntityHandle& volume, + * @brief Finds the volume containing a given point. + * + * @param xyz A 3-element array representing the coordinates of the point. + * @param[out] volume The volume containing the point. + * @param uvw Optional. A 3-element array representing the unit direction to + * be used when firing a test ray. Default is NULL. + * + * @return Returns an ErrorCode indicating the success or failure of the + * operation. + */ + ErrorCode find_volume(const double xyz[3], EntityHandle& volume, const double* uvw = NULL); #endif /** - * @brief 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. - * - * @param volume The volume to be tested. - * @param surface The surface to be tested. - * @param xyz A 3-element array representing the coordinates of the point. - * @param uvw A 3-element array representing the unit direction from the point to the volume. - * @param[out] result The result of the operation. 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. - * - * @return Returns an ErrorCode indicating the success or failure of the operation. - */ + * @brief 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. + * + * @param volume The volume to be tested. + * @param surface The surface to be tested. + * @param xyz A 3-element array representing the coordinates of the point. + * @param uvw A 3-element array representing the unit direction from the point + * to the volume. + * @param[out] result The result of the operation. 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. + * + * @return 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); + const double xyz[3], const double uvw[3], + int& result, const RayHistory* history = NULL); /** - * @brief Finds the point in a specified volume that is closest to a given location. - * - * @param volume The volume to be searched. - * @param point A 3-element array representing the coordinates of the location. - * @param[out] result The distance from the location to the closest point in the volume. - * @param[out] surface Optional. The handle of the surface on which the closest point lies. Default is 0. - * - * @return 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); + * @brief Finds the point in a specified volume that is closest to a given + * location. + * + * @param volume The volume to be searched. + * @param point A 3-element array representing the coordinates of the + * location. + * @param[out] result The distance from the location to the closest point in + * the volume. + * @param[out] surface Optional. The handle of the surface on which the + * closest point lies. Default is 0. + * + * @return 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); /** - * @brief Measures the volume of a specified volume. - * - * @param volume The volume to be measured. - * @param[out] result The measured volume. - * - * @return Returns an ErrorCode indicating the success or failure of the operation. - */ + * @brief Measures the volume of a specified volume. + * + * @param volume The volume to be measured. + * @param[out] result The measured volume. + * + * @return Returns an ErrorCode indicating the success or failure of the + * operation. + */ ErrorCode measure_volume(EntityHandle volume, double& result); /** - * @brief Measures the area of a specified surface. - * - * @param surface The surface to be measured. - * @param[out] result The measured area. - * - * @return Returns an ErrorCode indicating the success or failure of the operation. - */ + * @brief Measures the area of a specified surface. + * + * @param surface The surface to be measured. + * @param[out] result The measured area. + * + * @return Returns an ErrorCode indicating the success or failure of the + * operation. + */ ErrorCode measure_area(EntityHandle surface, double& result); /** - * @brief 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. - * - * @param volume The volume with respect to which the sense is determined. - * @param num_surfaces The number of surfaces for which to determine the sense. - * @param surfaces An array of handles of the surfaces for which to determine the sense. - * @param[out] senses_out An array in which to store the determined senses. - * - * @return 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); + * @brief 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. + * + * @param volume The volume with respect to which the sense is determined. + * @param num_surfaces The number of surfaces for which to determine the + * sense. + * @param surfaces An array of handles of the surfaces for which to determine + * the sense. + * @param[out] senses_out An array in which to store the determined senses. + * + * @return 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); /** - * @brief 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. - * - * @param volume The volume with respect to which the sense is determined. - * @param surface The handle of the surface for which to determine the sense. - * @param[out] sense_out The determined sense. - * - * @return Returns an ErrorCode indicating the success or failure of the operation. - */ - ErrorCode surface_sense(EntityHandle volume, - EntityHandle surface, + * @brief 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. + * + * @param volume The volume with respect to which the sense is determined. + * @param surface The handle of the surface for which to determine the sense. + * @param[out] sense_out The determined sense. + * + * @return Returns an ErrorCode indicating the success or failure of the + * operation. + */ + ErrorCode surface_sense(EntityHandle volume, EntityHandle surface, int& sense_out); /** - * @brief Gets the angle between a specified surface and a ray from a given point in a specified direction. - * - * @param surf The surface with respect to which the angle is determined. - * @param xyz A 3-element array representing the coordinates of the point. - * @param angle[out] A 3-element array in which to store the determined angle. - * @param history Optional. A pointer to a RayHistory object for storing the ray's path. Default is NULL. - * - * @return Returns an ErrorCode indicating the success or failure of the operation. - */ - ErrorCode get_angle(EntityHandle surf, - const double xyz[3], - double angle[3], + * @brief Gets the angle between a specified surface and a ray from a given + * point in a specified direction. + * + * @param surf The surface with respect to which the angle is determined. + * @param xyz A 3-element array representing the coordinates of the point. + * @param angle[out] A 3-element array in which to store the determined angle. + * @param history Optional. A pointer to a RayHistory object for storing the + * ray's path. Default is NULL. + * + * @return 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); /** - * @brief Finds the volume adjacent to a specified surface and volume. - * - * @param surface The surface across which to find the adjacent volume. - * @param old_volume The volume from which to find the adjacent volume. - * @param[out] new_volume The handle of the adjacent volume. - * - * @return Returns an ErrorCode indicating the success or failure of the operation. - */ - ErrorCode next_vol(EntityHandle surface, - EntityHandle old_volume, + * @brief Finds the volume adjacent to a specified surface and volume. + * + * @param surface The surface across which to find the adjacent volume. + * @param old_volume The volume from which to find the adjacent volume. + * @param[out] new_volume The handle of the adjacent volume. + * + * @return Returns an ErrorCode indicating the success or failure of the + * operation. + */ + ErrorCode next_vol(EntityHandle surface, EntityHandle old_volume, EntityHandle& new_volume); /* SECTION III: Indexing & Cross-referencing */ @@ -553,12 +568,13 @@ class DagMC { int dimension = 0, const std::string* value = NULL); /** - * @brief Checks if a given volume is the implicit complement. - * - * @param volume The volume to be checked. - * - * @return Returns true if the volume is the implicit complement, false otherwise. - */ + * @brief Checks if a given volume is the implicit complement. + * + * @param volume The volume to be checked. + * + * @return Returns true if the volume is the implicit complement, false + * otherwise. + */ bool is_implicit_complement(EntityHandle volume); /** get the tag for the "name" of a surface == global ID */ diff --git a/src/dagmc/dagmcmetadata.hpp b/src/dagmc/dagmcmetadata.hpp index 1f4346178..8cc76a667 100644 --- a/src/dagmc/dagmcmetadata.hpp +++ b/src/dagmc/dagmcmetadata.hpp @@ -8,11 +8,11 @@ class dagmcMetaData { public: - /** - * @brief Constructs a new DagmcMetadata object. - * - * @param dagmc A pointer to the DagMC instance associated with this metadata. - */ // Constructor + /** + * @brief Constructs a new DagmcMetadata object. + * + * @param dagmc A pointer to the DagMC instance associated with this metadata. + */ // Constructor dagmcMetaData(moab::DagMC* DAGptr, bool verbosity = false, bool require_density_present = true); @@ -27,7 +27,8 @@ class dagmcMetaData { * This function reads the properties from the associated DagMC instance and * stores them in internal data structures for efficient access. */ - void load_property_data(); void load_property_data(); + void load_property_data(); + void load_property_data(); /** * @brief Retrieves a specified property for a given volume. @@ -37,8 +38,7 @@ class dagmcMetaData { * * @return Returns the value of the specified property for the given volume. */ - std::string get_volume_property(std::string property, - moab::EntityHandle vol); + std::string get_volume_property(std::string property, moab::EntityHandle vol); // get a property for the specified volume, treats the vol parameter as // an index by default and as an ID if idx is false. @@ -54,15 +54,15 @@ class dagmcMetaData { * * @return Returns the value of the specified property for the given volume. */ - std::string get_volume_property(std::string property, - int vol, + std::string get_volume_property(std::string property, int vol, bool idx = true); /** * @brief Retrieves a specified property for a given surface. * * @param property The name of the property to retrieve. - * @param surface The handle of the surface for which to retrieve the property. + * @param surface The handle of the surface for which to retrieve the + * property. * * @return Returns the value of the specified property for the given surface. */ @@ -80,15 +80,15 @@ class dagmcMetaData { * * @return Returns the value of the specified property for the given surface. */ - std::string get_surface_property(std::string property, - int surface, + std::string get_surface_property(std::string property, int surface, bool idx = true); - /** + /** * @brief Unpacks a string into a vector of substrings. * - * The input string is expected to be of the form "delimiterdelimiterdelimiter". - * The function will unpack this into a vector of the form "data[0],data[1],...". + * The input string is expected to be of the form + * "delimiterdelimiterdelimiter". The function will unpack this + * into a vector of the form "data[0],data[1],...". * * @param to_unpack The string to unpack. * @param delimiters The delimiters used to separate the data in the string. @@ -107,15 +107,17 @@ class dagmcMetaData { * * @return Returns a pair of strings. The first element of the pair is the * substring before the first occurrence of the delimiter. The second - * element is the substring after the first occurrence of the delimiter. + * element is the substring after the first occurrence of the + * delimiter. */ std::pair split_string(std::string property_string, std::string delimiter); - /** + /** * @brief Extracts the value of a desired key from a property string. * - * The property string is expected to be of the form "key:property/key:property". + * The property string is expected to be of the form + * "key:property/key:property". * * @param property_string The string containing the properties. * @param property The key for which to return the value. @@ -127,10 +129,8 @@ class dagmcMetaData { * * @return Returns the value of the specified key from the property string. */ - std::string return_property(std::string property_string, - std::string property, - std::string delimiter = ":", - bool chopped = true); + std::string return_property(std::string property_string, std::string property, + std::string delimiter = ":", bool chopped = true); /** * @brief Tests if a string can be converted to an integer. @@ -144,7 +144,7 @@ class dagmcMetaData { // private member functions private: - /** + /** * @brief Parses the material data from the associated DagMC instance. */ void parse_material_data(); @@ -176,7 +176,8 @@ class dagmcMetaData { /** * @brief Parses property for entities with the specified dimension and - * delimiters. Optionally removes duplicate property values if necessary. + * delimiters. Optionally removes duplicate property values if + * necessary. * * @param property The name of the property to retrieve. * @param dimension The dimension of the entities for which to retrieve the @@ -189,8 +190,7 @@ class dagmcMetaData { * are vectors of property values. */ std::map> - get_property_assignments(std::string property, - int dimension, + get_property_assignments(std::string property, int dimension, std::string delimiters, bool remove_duplicates = true); @@ -201,7 +201,8 @@ class dagmcMetaData { * * @return Returns a vector of properties with all duplicates removed. */ - std::vector remove_duplicate_properties(std::vector properties); + std::vector remove_duplicate_properties( + std::vector properties); /** * @brief Removes less informative properties from a set of properties. @@ -279,7 +280,8 @@ class dagmcMetaData { * @brief Map storing the importance data for each entity. * * The keys are the entity handles. The values are maps where the keys are - * particle types and the values are the importance values for those particles. + * particle types and the values are the importance values for those + * particles. */ std::map> importance_map;