From 8b041b2154a9fee7d0b34bbeeb99bacebd9861a5 Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Sun, 18 Feb 2024 23:57:44 -0600 Subject: [PATCH 01/13] Adding documentation to DAGMC header. Needs review --- src/dagmc/DagMC.hpp | 136 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 131 insertions(+), 5 deletions(-) diff --git a/src/dagmc/DagMC.hpp b/src/dagmc/DagMC.hpp index 45744bc28..6b422b91e 100644 --- a/src/dagmc/DagMC.hpp +++ b/src/dagmc/DagMC.hpp @@ -212,48 +212,168 @@ 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 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 of the ray. Default is 1. + * @param stats Optional. A pointer to a TrvStats object for storing traversal statistics. + * + * @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, 0 if it is outside, and -1 if the point is on the boundary. + * @param uvw Optional. A 3-element array representing the direction from the point to the volume. Default is NULL. + * @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 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, 0 if it is outside, and -1 if the point is on the boundary. + * + * @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 direction from the point to the volume. 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 Tests whether a given point is on the boundary of a specified volume and surface. + * + * @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 direction from the point to the volume. + * @param[out] result The result of the operation. It will be set to 1 if the point is on the boundary, 0 otherwise. + * @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 test_volume_boundary(const EntityHandle volume, const EntityHandle surface, 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 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. + */ ErrorCode measure_area(EntityHandle surface, double& result); + /** + * @brief Determines the sense of one or more surfaces with respect to a specified 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. + * + * @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 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, - EntityHandle& new_volume); - - /* SECTION III: Indexing & Cross-referencing */ + EntityHandle& new_volume); /* SECTION III: Indexing & Cross-referencing */ public: /** Most calling apps refer to geometric entities with a combination of * base-1/0 ordinal index (or rank) and global ID (or name). @@ -397,7 +517,13 @@ class DagMC { std::vector& return_list, 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. + */ bool is_implicit_complement(EntityHandle volume); /** get the tag for the "name" of a surface == global ID */ From 04ba4c4f6134332fe70fd048a8bc902d204ae947 Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Thu, 22 Feb 2024 23:35:49 -0600 Subject: [PATCH 02/13] Corrections/updates to the documentation --- src/dagmc/DagMC.hpp | 99 ++++++++++++++++++++++++++++++--------------- 1 file changed, 67 insertions(+), 32 deletions(-) diff --git a/src/dagmc/DagMC.hpp b/src/dagmc/DagMC.hpp index 6b422b91e..09afe6b0d 100644 --- a/src/dagmc/DagMC.hpp +++ b/src/dagmc/DagMC.hpp @@ -218,20 +218,24 @@ class DagMC { * * @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 direction 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 of the ray. Default is 1. - * @param stats Optional. A pointer to a TrvStats object for storing traversal statistics. + * @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, + 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); @@ -240,25 +244,32 @@ class DagMC { * * @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, 0 if it is outside, and -1 if the point is on the boundary. - * @param uvw Optional. A 3-element array representing the direction from the point to the volume. Default is NULL. - * @param history Optional. A pointer to a RayHistory object for storing the ray's path. Default is NULL. + * @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. + * @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, + 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, 0 if it is outside, and -1 if the point is on the boundary. + * @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], + ErrorCode point_in_volume_slow(const EntityHandle volume, + const double xyz[3], int& result); #if MOAB_VERSION_MAJOR == 5 && MOAB_VERSION_MINOR > 2 @@ -267,30 +278,40 @@ class DagMC { * * @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 direction from the point to the volume. Default is NULL. + * @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, + ErrorCode find_volume(const double xyz[3], + EntityHandle& volume, const double* uvw = NULL); #endif /** - * @brief Tests whether a given point is on the boundary of a specified volume and surface. + * @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 direction from the point to the volume. - * @param[out] result The result of the operation. It will be set to 1 if the point is on the boundary, 0 otherwise. - * @param history Optional. A pointer to a RayHistory object for storing the ray's path. Default is NULL. + * @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. @@ -302,8 +323,10 @@ class DagMC { * * @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); + ErrorCode closest_to_location(EntityHandle volume, + const double point[3], + double& result, + EntityHandle* surface = 0); /** * @brief Measures the volume of a specified volume. @@ -328,6 +351,8 @@ class DagMC { /** * @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. @@ -335,19 +360,24 @@ class DagMC { * * @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); + 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, + ErrorCode surface_sense(EntityHandle volume, + EntityHandle surface, int& sense_out); /** @@ -355,12 +385,14 @@ class DagMC { * * @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 A 3-element array in which to store the determined angle. + * @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], + ErrorCode get_angle(EntityHandle surf, + const double xyz[3], + double angle[3], const RayHistory* history = NULL); /** @@ -372,8 +404,11 @@ class DagMC { * * @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 */ + ErrorCode next_vol(EntityHandle surface, + EntityHandle old_volume, + EntityHandle& new_volume); + + /* SECTION III: Indexing & Cross-referencing */ public: /** Most calling apps refer to geometric entities with a combination of * base-1/0 ordinal index (or rank) and global ID (or name). From 72fd3f7f274f327ea18c97036f2bc03a1d5cd910 Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Sun, 25 Feb 2024 23:39:57 -0600 Subject: [PATCH 03/13] Updating/adding inline documentation for the metadata class --- src/dagmc/dagmcmetadata.hpp | 301 +++++++++++++++++++++++++++++------- 1 file changed, 249 insertions(+), 52 deletions(-) diff --git a/src/dagmc/dagmcmetadata.hpp b/src/dagmc/dagmcmetadata.hpp index 76a4fbd24..1f4346178 100644 --- a/src/dagmc/dagmcmetadata.hpp +++ b/src/dagmc/dagmcmetadata.hpp @@ -8,118 +8,315 @@ class dagmcMetaData { public: - // 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); - // Destructor + /** + * @brief Default destructor for the dagmcMetadata class. + */ ~dagmcMetaData() = default; - // load the dagmc properties into maps - void load_property_data(); + /** + * @brief Loads the DagMC properties into internal data maps. + * + * 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(); + + /** + * @brief Retrieves a specified property for a given volume. + * + * @param property The name of the property to retrieve. + * @param vol The handle of the volume for which to retrieve the property. + * + * @return Returns the value of the specified property for the given volume. + */ + std::string get_volume_property(std::string property, + moab::EntityHandle vol); - // get a given property on a volume - 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. - std::string get_volume_property(std::string property, int vol, + + /** + * @brief Retrieves a specified property for a given volume. + * + * @param property The name of the property to retrieve. + * @param vol The ID of the volume for which to retrieve the property. + * @param idx Optional. If true, the vol parameter will be treated as an + * index into the DAGMC data structures. If false, it will be treated as a + * volume ID. Default is true. + * + * @return Returns the value of the specified property for the given volume. + */ + std::string get_volume_property(std::string property, + int vol, bool idx = true); - // get a given property on a surface + /** + * @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. + * + * @return Returns the value of the specified property for the given surface. + */ std::string get_surface_property(std::string property, moab::EntityHandle surface); - // get a property for the specified surface, treats the surface parameter as - // an index by default and as an ID if idx is false. - std::string get_surface_property(std::string property, int surface, + + /** + * @brief Retrieves a specified property for a given surface. + * + * @param property The name of the property to retrieve. + * @param surface The ID of the surface for which to retrieve the property. + * @param idx Optional. If true, the surface parameter will be treated as an + * index into the DAGMC data structures. If false, it will be treated as a + * surface ID. Default is true. + * + * @return Returns the value of the specified property for the given surface. + */ + std::string get_surface_property(std::string property, + int surface, bool idx = true); - // unpack the packed string of the form - // delimeterdelimiterdelimiter into a vector of the form - // data[0],data[1] etc + /** + * @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],...". + * + * @param to_unpack The string to unpack. + * @param delimiters The delimiters used to separate the data in the string. + * Default is "|". + * + * @return Returns a vector of substrings extracted from the input string. + */ std::vector unpack_string(std::string to_unpack, std::string delimiters = "|"); - // splits a string on the basis of the first delimiter it finds + /** + * @brief Splits a string on the basis of the first delimiter it finds. + * + * @param property_string The string to be split. + * @param delimiter The delimiter on which to split the string. + * + * @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. + */ std::pair split_string(std::string property_string, std::string delimiter); - // from a string of the form key:property/key:property - // return the value of a desired key - std::string return_property(std::string property_string, std::string property, - std::string delimiter = ":", bool chopped = true); + /** + * @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". + * + * @param property_string The string containing the properties. + * @param property The key for which to return the value. + * @param delimiter The delimiter used to separate the keys and values in the + * property string. Default is ":". + * @param chopped Optional. If true, the function will return the property + * value after removing the key and delimiter. If false, it + * will return the property value as is. Default is true. + * + * @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); - // test to see if string is an int + /** + * @brief Tests if a string can be converted to an integer. + * + * @param value The string to be tested. + * + * @return Returns true if the string can be converted to an integer, + * false otherwise. + */ bool try_to_make_int(std::string value); // private member functions private: - // parse the material data + /** + * @brief Parses the material data from the associated DagMC instance. + */ void parse_material_data(); - // parse the importance data + + /** + * @brief Parses the importance data from the associated DagMC instance. + */ void parse_importance_data(); - // parse the boundary data + + /** + * @brief Parses the boundary data from the associated DagMC instance. + */ void parse_boundary_data(); - // parse the tally data + + /** + * @brief Parses the tally surface data from the associated DagMC instance. + */ void parse_tally_surface_data(); - // parse the tally data + + /** + * @brief Parses the tally volume data from the associated DagMC instance. + */ void parse_tally_volume_data(); - // finalise the count data + + /** + * @brief Finalizes the counters after all data has been parsed. + */ void finalise_counters(); - // Parse property for entities with the specified dimension and delimiters. - // Optionally remove duplicate property values if necessary. + /** + * @brief Parses property for entities with the specified dimension and + * 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 + * property. + * @param delimiters The delimiters used to separate the data in the string. + * @param remove_duplicates Optional. If true, the function will remove + * duplicate property values. Default is true. + * + * @return Returns a map where the keys are the entity handles and the values + * 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); - // remove duplicate properties from the vector of properties - std::vector remove_duplicate_properties( - std::vector properties); + /** + * @brief Removes duplicate properties from a vector of properties. + * + * @param properties The vector of properties from which to remove duplicates. + * + * @return Returns a vector of properties with all duplicates removed. + */ + std::vector remove_duplicate_properties(std::vector properties); - // from a given set remove any matches if they are found in order to keep the - // the information rich version. ie. if we find both neutron and neutron/1.0 - // keep the second one + /** + * @brief Removes less informative properties from a set of properties. + * + * If a property and a more informative version of that property (e.g., + * "neutron" and "neutron/1.0") are both present in the set, this function + * removes the less informative version. + * + * @param properties_set The set of properties from which to remove less + * informative properties. + * + * @return Returns a set of properties with all less informative properties + * removed. + */ std::set set_remove_rich(std::set properties_set); std::string to_lower(const std::string input); // public member variables public: - // material property data map, mat:/density value - // this is the full string in the form mat:/density: + /** + * @brief Map storing the material property data for each volume. + * + * The keys are the entity handles of the volumes. The values are strings + * in the form "mat:/density:". + */ std::map volume_material_property_data_eh; - // material data map, mat: + /** + * @brief Map storing the material data for each volume. + * + * The keys are the entity handles of the volumes. The values are strings + * in the form "mat:". + */ std::map volume_material_data_eh; - // density data map, rho: value + /** + * @brief Map storing the density data for each volume. + * + * The keys are the entity handles of the volumes. The values are strings + * in the form "rho:". + */ std::map volume_density_data_eh; - // importance data map, importance: value + /** + * @brief Map storing the importance data for each volume. + * + * The keys are the entity handles of the volumes. The values are strings + * in the form "importance:". + */ std::map volume_importance_data_eh; - // surface boundary data, boundary: value + /** + * @brief Map storing the boundary data for each surface. + * + * The keys are the entity handles of the surfaces. The values are strings + * in the form "boundary:". + */ std::map surface_boundary_data_eh; - // tally map + /** + * @brief Map storing the tally data. + * + * The keys are the entity handles. The values are strings representing + * the tally data. + */ std::map tally_data_eh; - // set to collect all particle types in the problem + /** + * @brief Set to collect all particle types in the problem. + */ std::set imp_particles; - // map of importance data + + /** + * @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. + */ std::map> importance_map; // private member variables private: - moab::DagMC* DAG; // Pointer to DAGMC instance - bool verbose; // Provide additional output while setting up and parsing - // properties - bool require_density; // Require that all volumes have a specified density - // value - std::vector - metadata_keywords; // Keywords supported by the metadata manager - std::map keyword_synonyms; // Keyword synonyms + /** + * @brief Pointer to the DAGMC instance. + */ + moab::DagMC* DAG; + + /** + * @brief Flag to control verbosity. + * + * If true, the metadata manager will provide additional output while setting + * up and parsing properties. + */ + bool verbose; + + /** + * @brief Flag to control density requirement. + * + * If true, the metadata manager will require that all volumes have a + * specified density value. + */ + bool require_density; + + /** + * @brief List of keywords supported by the metadata manager. + */ + std::vector metadata_keywords; + + /** + * @brief Map of property keyword synonyms. + * + */ + std::map keyword_synonyms; + // Some constant keyword values const std::string graveyard_str{"Graveyard"}; const std::string vacuum_str{"Vacuum"}; From 0d6fe7e18cd6ce773275366310bca2e2f531162e Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Sun, 25 Feb 2024 23:43:46 -0600 Subject: [PATCH 04/13] Applying style guide --- src/dagmc/DagMC.hpp | 348 +++++++++++++++++++----------------- src/dagmc/dagmcmetadata.hpp | 60 ++++--- 2 files changed, 213 insertions(+), 195 deletions(-) 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; From dabcd73e20821aa59d9b8644b1a3b2f21714325b Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Sun, 25 Feb 2024 23:46:27 -0600 Subject: [PATCH 05/13] Updating changelog --- doc/CHANGELOG.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/CHANGELOG.rst b/doc/CHANGELOG.rst index 91a98c3de..c9d4991ca 100644 --- a/doc/CHANGELOG.rst +++ b/doc/CHANGELOG.rst @@ -15,6 +15,7 @@ Next version * Update README regarding OpenMC (#938) * Simplify Housekeeping Process for DAGMC (#943) * Allow Double Down v1.1.0 Installation in Dockerfile (#929) + * Inline documentation improvements (#945) v3.2.3 ==================== From e8656f1905aa9fe10593ae41576c9702267e8eba Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Mon, 26 Feb 2024 08:20:12 -0600 Subject: [PATCH 06/13] Remove redundant method signature line --- src/dagmc/dagmcmetadata.hpp | 1 - 1 file changed, 1 deletion(-) diff --git a/src/dagmc/dagmcmetadata.hpp b/src/dagmc/dagmcmetadata.hpp index 8cc76a667..346c88005 100644 --- a/src/dagmc/dagmcmetadata.hpp +++ b/src/dagmc/dagmcmetadata.hpp @@ -28,7 +28,6 @@ class dagmcMetaData { * stores them in internal data structures for efficient access. */ void load_property_data(); - void load_property_data(); /** * @brief Retrieves a specified property for a given volume. From b485a4315a905901919d355f11dddd1504750c00 Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Mon, 26 Feb 2024 21:34:30 -0600 Subject: [PATCH 07/13] Addressing comments in PR review --- src/dagmc/DagMC.hpp | 25 +++++++++++++++++-------- src/dagmc/dagmcmetadata.hpp | 13 +++++++++++++ 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/src/dagmc/DagMC.hpp b/src/dagmc/DagMC.hpp index affb71dbe..c18bed057 100644 --- a/src/dagmc/DagMC.hpp +++ b/src/dagmc/DagMC.hpp @@ -265,6 +265,12 @@ class DagMC { * @brief 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. + * * @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 @@ -283,7 +289,8 @@ class DagMC { * @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. + * be used when firing a test ray. Default is NULL. If no value is provided + * a random direction for the ray will be generated. * * @return Returns an ErrorCode indicating the success or failure of the * operation. @@ -305,11 +312,13 @@ class DagMC { * @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. + * @param[out] result The result of the operation. Set to 1 if ray is entering + * volume, or 0 if it is leaving. + * @param 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. * * @return Returns an ErrorCode indicating the success or failure of the * operation. @@ -395,8 +404,8 @@ class DagMC { int& sense_out); /** - * @brief Gets the angle between a specified surface and a ray from a given - * point in a specified direction. + * @brief Gets the angle between the normal of a specified surface and a ray + * from the ray origin 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. diff --git a/src/dagmc/dagmcmetadata.hpp b/src/dagmc/dagmcmetadata.hpp index 346c88005..bb6f2ba48 100644 --- a/src/dagmc/dagmcmetadata.hpp +++ b/src/dagmc/dagmcmetadata.hpp @@ -7,6 +7,19 @@ #include "logger.hpp" class dagmcMetaData { +/** + * @class dagmcMetaData + * @brief A class to manage metadata in DAGMC models. + * + * The dagmcMetaData class provides functionality to parse and manage metadata + * that defines properties associated with volumes and surfaces in a DAGMC model + * (a .h5m file). These properties can include material assignments, density + * values, importance values, boundary conditions, and tally assignments. + * + * The class provides functions to parse metadata from the model group meshsets + * based on a set of keywords (e.g. "mat" or "rho"), retrieve metadata for + * specific entities, and check the validity of the discovered metadata. + */ public: /** * @brief Constructs a new DagmcMetadata object. From 19b7faf950f49e519a81635584861ffe07607640 Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Mon, 26 Feb 2024 21:46:06 -0600 Subject: [PATCH 08/13] Adding docs for dagmcmetadata constructor and remove duplicat props --- src/dagmc/dagmcmetadata.hpp | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/src/dagmc/dagmcmetadata.hpp b/src/dagmc/dagmcmetadata.hpp index bb6f2ba48..6c5c92924 100644 --- a/src/dagmc/dagmcmetadata.hpp +++ b/src/dagmc/dagmcmetadata.hpp @@ -24,9 +24,13 @@ class dagmcMetaData { /** * @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, + * @param DAGptr A pointer to the DagMC instance associated with this metadata. + * @param verbosity A boolean flag to control verbosity. If true, the metadata manager + * will provide additional output while setting up and parsing properties. + * @param density A boolean flag to control density requirement. If true, the metadata + * manager will require that all volumes have a specified density value. + */ + dagmcMetaData(moab::DagMC* DAGptr, bool verbosity = false, bool require_density_present = true); /** @@ -209,6 +213,11 @@ class dagmcMetaData { /** * @brief Removes duplicate properties from a vector of properties. * + * Group names are parsed in such a way that the property and value are two separate + * entries in the array. For example, a tag like "particle:neutron/1.0" will return as + * "neutron" and "neutron/1.0". This function searches each item for its more + * information-rich partner and removes the degenerate item(s). + * * @param properties The vector of properties from which to remove duplicates. * * @return Returns a vector of properties with all duplicates removed. From d97c300ae6f0c3d69d3391f88c7c6b5f2387a518 Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Mon, 26 Feb 2024 21:47:55 -0600 Subject: [PATCH 09/13] Apply suggestions from @ahnaf-tahmid-chowdhury Co-authored-by: Ahnaf Tahmid Chowdhury --- src/dagmc/dagmcmetadata.hpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/dagmc/dagmcmetadata.hpp b/src/dagmc/dagmcmetadata.hpp index 6c5c92924..535b86dd3 100644 --- a/src/dagmc/dagmcmetadata.hpp +++ b/src/dagmc/dagmcmetadata.hpp @@ -124,7 +124,7 @@ 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. + * delimiter. */ std::pair split_string(std::string property_string, std::string delimiter); @@ -193,7 +193,7 @@ class dagmcMetaData { /** * @brief Parses property for entities with the specified dimension and * delimiters. Optionally removes duplicate property values if - * necessary. + * necessary. * * @param property The name of the property to retrieve. * @param dimension The dimension of the entities for which to retrieve the From eb30c20cfdd1fed2320b0cafb02e10533267855b Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Mon, 26 Feb 2024 21:55:27 -0600 Subject: [PATCH 10/13] Adding more information on private parse_ methods --- src/dagmc/dagmcmetadata.hpp | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/src/dagmc/dagmcmetadata.hpp b/src/dagmc/dagmcmetadata.hpp index 535b86dd3..a259011a6 100644 --- a/src/dagmc/dagmcmetadata.hpp +++ b/src/dagmc/dagmcmetadata.hpp @@ -161,35 +161,39 @@ class dagmcMetaData { // private member functions private: /** - * @brief Parses the material data from the associated DagMC instance. + * @brief Parses the material and density assignmens from group meshsets in + * the associated DagMC instance using the "mat" and "rho" keywords, + * respectively. Populates the volume_material_property_data_eh, + * volume_material_data_eh, and volume_density_data_eh maps. */ void parse_material_data(); /** - * @brief Parses the importance data from the associated DagMC instance. + * @brief Parses the volume importance data from group meshsets in the + * associated DagMC instance using the "importance" keyword. Populates the + * volume_importance_data_eh map. */ void parse_importance_data(); /** - * @brief Parses the boundary data from the associated DagMC instance. + * @brief Parses the boundary data from group meshsets in the the associated + * DagMC instance using the "boundary" keyword. Populates the + * surface_boundary_data_eh map. */ void parse_boundary_data(); /** - * @brief Parses the tally surface data from the associated DagMC instance. + * @brief Parses the tally surface data from group meshsets in the associated + * DagMC instance using the "tally" keyword. Populates the tally_data_eh map. */ void parse_tally_surface_data(); /** - * @brief Parses the tally volume data from the associated DagMC instance. + * @brief Parses the tally volume data from group meshsets in the associated + * DagMC instance using the "tally" keyword. Populates the tally_data_eh map. */ void parse_tally_volume_data(); - /** - * @brief Finalizes the counters after all data has been parsed. - */ - void finalise_counters(); - /** * @brief Parses property for entities with the specified dimension and * delimiters. Optionally removes duplicate property values if From 3142099734e6dd2ce54c859761e930fdf4460025 Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Mon, 26 Feb 2024 22:52:35 -0600 Subject: [PATCH 11/13] Fix format --- src/dagmc/dagmcmetadata.hpp | 52 +++++++++++++++++++++---------------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/src/dagmc/dagmcmetadata.hpp b/src/dagmc/dagmcmetadata.hpp index a259011a6..90de31cf4 100644 --- a/src/dagmc/dagmcmetadata.hpp +++ b/src/dagmc/dagmcmetadata.hpp @@ -7,30 +7,35 @@ #include "logger.hpp" class dagmcMetaData { -/** - * @class dagmcMetaData - * @brief A class to manage metadata in DAGMC models. - * - * The dagmcMetaData class provides functionality to parse and manage metadata - * that defines properties associated with volumes and surfaces in a DAGMC model - * (a .h5m file). These properties can include material assignments, density - * values, importance values, boundary conditions, and tally assignments. - * - * The class provides functions to parse metadata from the model group meshsets - * based on a set of keywords (e.g. "mat" or "rho"), retrieve metadata for - * specific entities, and check the validity of the discovered metadata. - */ + /** + * @class dagmcMetaData + * @brief A class to manage metadata in DAGMC models. + * + * The dagmcMetaData class provides functionality to parse and manage metadata + * that defines properties associated with volumes and surfaces in a DAGMC + * model (a .h5m file). These properties can include material assignments, + * density values, importance values, boundary conditions, and tally + * assignments. + * + * The class provides functions to parse metadata from the model group + * meshsets based on a set of keywords (e.g. "mat" or "rho"), retrieve + * metadata for specific entities, and check the validity of the discovered + * metadata. + */ public: /** * @brief Constructs a new DagmcMetadata object. * - * @param DAGptr A pointer to the DagMC instance associated with this metadata. - * @param verbosity A boolean flag to control verbosity. If true, the metadata manager - * will provide additional output while setting up and parsing properties. - * @param density A boolean flag to control density requirement. If true, the metadata - * manager will require that all volumes have a specified density value. + * @param DAGptr A pointer to the DagMC instance associated with this + * metadata. + * @param verbosity A boolean flag to control verbosity. If true, the metadata + * manager will provide additional output while setting up and parsing + * properties. + * @param density A boolean flag to control density requirement. If true, the + * metadata manager will require that all volumes have a specified density + * value. */ - dagmcMetaData(moab::DagMC* DAGptr, bool verbosity = false, + dagmcMetaData(moab::DagMC* DAGptr, bool verbosity = false, bool require_density_present = true); /** @@ -217,10 +222,11 @@ class dagmcMetaData { /** * @brief Removes duplicate properties from a vector of properties. * - * Group names are parsed in such a way that the property and value are two separate - * entries in the array. For example, a tag like "particle:neutron/1.0" will return as - * "neutron" and "neutron/1.0". This function searches each item for its more - * information-rich partner and removes the degenerate item(s). + * Group names are parsed in such a way that the property and value are two + * separate entries in the array. For example, a tag like + * "particle:neutron/1.0" will return as "neutron" and "neutron/1.0". This + * function searches each item for its more information-rich partner and + * removes the degenerate item(s). * * @param properties The vector of properties from which to remove duplicates. * From bc6241aee9154b9e792010ca4ec4c7348cb991b0 Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Tue, 27 Feb 2024 10:32:46 -0600 Subject: [PATCH 12/13] Improvements to get_angle docs and other small updates. --- src/dagmc/DagMC.hpp | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/src/dagmc/DagMC.hpp b/src/dagmc/DagMC.hpp index c18bed057..e56c8528d 100644 --- a/src/dagmc/DagMC.hpp +++ b/src/dagmc/DagMC.hpp @@ -404,14 +404,22 @@ class DagMC { int& sense_out); /** - * @brief Gets the angle between the normal of a specified surface and a ray - * from the ray origin in a specified direction. + * @brief 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. * - * @param surf The surface with respect to which the angle is determined. + * 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. + * + * @param surf The surface for which a normal vector 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. + * @param angle[out] A 3-element array in which to store the determined + * surface normal. + * @param history Optional. A pointer to a RayHistory object storing + * previously hit triangles. Default is NULL. * * @return Returns an ErrorCode indicating the success or failure of the * operation. @@ -600,8 +608,7 @@ class DagMC { Tag sense_tag() { return GTT->get_sense_tag(); } private: - /** tokenize the metadata stored in group names - basically borrowed from - * ReadCGM.cpp */ + /** tokenize the metadata stored in group names */ void tokenize(const std::string& str, std::vector& tokens, const char* delimiters = "_") const; From 9a74ad64feb4bf68e0dd3fe31c4efe18cce7f6c7 Mon Sep 17 00:00:00 2001 From: Patrick Shriwise Date: Tue, 27 Feb 2024 12:00:03 -0600 Subject: [PATCH 13/13] Style fixes --- src/dagmc/DagMC.hpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/dagmc/DagMC.hpp b/src/dagmc/DagMC.hpp index e56c8528d..3053a0851 100644 --- a/src/dagmc/DagMC.hpp +++ b/src/dagmc/DagMC.hpp @@ -411,8 +411,8 @@ class DagMC { * 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. + * 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. * * @param surf The surface for which a normal vector is determined. * @param xyz A 3-element array representing the coordinates of the point.