feat(az_to_species): az_to_species now returns an expected and error type

this will allow for much easier checking if a particular a,z pair actually exists

.gitignore

@@ -72,6 +72,7 @@ subprojects/cppad/
 subprojects/libconfig/
 subprojects/libconstants/
 subprojects/liblogging/
+subprojects/.wraplock
 
 qhull.wrap
 quill.wrap

tests/composition/compositionTest.cpp

@@ -89,7 +89,7 @@ TEST_F(compositionTest, isotopeSpin) {
  * @par What this test proves:
  * - The default constructor is accessible and does not fail on basic initialization.
  * @par What this test does not prove:
- * - The state of the constructed object or the correctness of any of its methods.
+ * - The state of the constructed object or the correctness of its methods.
  */
 TEST_F(compositionTest, constructor) {
     fourdst::config::Config::getInstance().loadConfig(EXAMPLE_FILENAME);
@@ -431,6 +431,8 @@ TEST_F(compositionTest, getRegisteredSpecies) {
 
 TEST_F(compositionTest, getSpeciesFromAZ) {
     EXPECT_EQ(fourdst::atomic::O_12, fourdst::atomic::az_to_species(12, 8));
+    EXPECT_EQ(fourdst::atomic::SpeciesErrorType::SPECIES_SYMBOL_NOT_FOUND, fourdst::atomic::az_to_species(120, 38).error());
+    EXPECT_EQ(fourdst::atomic::SpeciesErrorType::ELEMENT_SYMBOL_NOT_FOUND, fourdst::atomic::az_to_species(120, 500).error());
 }
 
 TEST_F(compositionTest, constructorWithSymbolsVectorAndSet) {

utils/atomic/format.py

@@ -224,17 +224,33 @@ def formatHeader(dataFrame):
 #include "fourdst/composition/atomicSpecies.h"
 #include "fourdst/composition/elements.h"
 
+#include <expected> // For std::expected
+
 namespace fourdst::atomic {{
     // Instantiate all species as static const objects.
     {'\n    '.join([formatSpecies(row)[0] for index, row in dataFrame.iterrows()])}
     
     // Create a map from species name (e.g., "H-1") to a pointer to the species object.
-    static const std::unordered_map<std::string, const Species*> species = {{
+    static const std::unordered_map<std::string, const Species&> species = {{
         {'\n        '.join([f'{{"{row["el"].strip()}-{row["a"]}", {mkInstanceName(row)}}},' for index, row in dataFrame.iterrows()])}
     }};
-    Species az_to_species(const int a, const int z) {{
+    
-    const std::string element_symbol = element_symbol_map.at(static_cast<uint8_t>(z));
+    // Create an enum to represent possible error types when looking up species.
+    enum class SpeciesErrorType {{
+        ELEMENT_SYMBOL_NOT_FOUND,
+        SPECIES_SYMBOL_NOT_FOUND
+    }};
+    
+    // Function to look up a species by its atomic number (Z) and mass number (A).
+    inline std::expected<Species, SpeciesErrorType> az_to_species(const int a, const int z) {{
+        if (!element_symbol_map.contains(static_cast<uint8_t>(z))) {{
+            return std::unexpected(SpeciesErrorType::ELEMENT_SYMBOL_NOT_FOUND);
+        }}
+        const std::string element_symbol = element_symbol_map.at(static_cast<uint8_t>(z));
         const std::string species_symbol = element_symbol + "-" + std::to_string(a);
+        if (!species.contains(species_symbol)) {{
+            return std::unexpected(SpeciesErrorType::SPECIES_SYMBOL_NOT_FOUND);
+        }}
         return species.at(species_symbol);
     }};