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"};