diff --git a/doc/CHANGELOG.rst b/doc/CHANGELOG.rst index ffea060d0..5ee6d4609 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 #944) + * Inline documentation improvements (#945) v3.2.3 ==================== diff --git a/src/dagmc/DagMC.hpp b/src/dagmc/DagMC.hpp index 45744bc28..3053a0851 100644 --- a/src/dagmc/DagMC.hpp +++ b/src/dagmc/DagMC.hpp @@ -212,44 +212,231 @@ 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, 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, const RayHistory* history = NULL); - + /** + * @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 + * 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. 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. + */ 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. 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. + */ 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. + * + * 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, int& sense_out); + /** + * @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. + * + * 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 + * 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. + */ 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); @@ -397,7 +584,14 @@ 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 */ @@ -414,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; diff --git a/src/dagmc/dagmcmetadata.hpp b/src/dagmc/dagmcmetadata.hpp index 76a4fbd24..90de31cf4 100644 --- a/src/dagmc/dagmcmetadata.hpp +++ b/src/dagmc/dagmcmetadata.hpp @@ -7,119 +7,349 @@ #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: - // Constructor + /** + * @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. + */ 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 + /** + * @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(); - // get a given property on a volume + /** + * @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 property for the specified volume, treats the vol parameter as // an index by default and as an ID if idx is false. + + /** + * @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. + + /** + * @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 + /** + * @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 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(); - // parse the importance data + + /** + * @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(); - // parse the boundary data + + /** + * @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(); - // parse the tally data + + /** + * @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(); - // parse the tally data + + /** + * @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(); - // finalise the count data - 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, std::string delimiters, bool remove_duplicates = true); - // remove duplicate properties from the vector of properties + /** + * @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. + */ 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"};