Add optional year attribute to Level class

Allows differentiating between computational methods or functionals released in different years, such as b97d3 vs. b97d3 (2023). Includes validation for 4-digit year integers and updates string representations to reflect the version.

This means that a user could add 'year' as a key in the input.yml for any of the {job}_level/arkane_level_of_theory, however, it will only be consumed when it's in arkane_level_of_theory. For {job}_level, it will be ignored (and user will be warned). The reason why this exists is because Level.build() iterates `allowed_keys` and passes them to the `__init__`. If we wanted to seriously enforce the year **only** for `arkane_level_of_theory` it would then need some serious refactoring to put it as a standalone attribute on ARC that attaches to arkane_level_of_theory I believe.

Author: calvinp0

arc/level.py

@@ -39,6 +39,7 @@ class Level(object):
         args (Dict[Dict[str, str]], optional): Additional arguments provided to the software.
                                                Different than the ``args`` in ``LevelOfTheory``.
         compatible_ess (list, optional): Entries are names of compatible ESS. Not in ``LevelOfTheory``.
+        year (int, optional): Optional 4-digit year suffix for differentiating methods such as b97d3/b97d32023.
     """
 
     def __init__(self,
@@ -56,6 +57,7 @@ def __init__(self,
                  solvent: Optional[str] = None,
                  solvation_scheme_level: Optional['Level'] = None,
                  args: Optional[Union[Dict[str, str], Iterable, str]] = None,
+                 year: Optional[int] = None,
                  ):
         self.repr = repr
         self.method = method
@@ -88,6 +90,12 @@ def __init__(self,
                 'Both solvation method and solvent must be defined together, or both must be None. '
                 f'Got solvation method = "{self.solvation_method}", solvent = "{self.solvent}".'
             )
+        if year is not None:
+            self.year = int(year)
+            if self.year < 1000 or self.year > 9999:
+                raise ValueError(f'year must be a 4-digit integer (1000-9999), got {self.year}.')
+        else:
+            self.year = None
         self.args = args or {'keyword': dict(), 'block': dict()}
 
         if self.repr is not None:
@@ -122,6 +130,8 @@ def __str__(self) -> str:
         str_ = self.method
         if self.basis is not None:
             str_ += f'/{self.basis}'
+        if self.year is not None:
+            str_ += f', year: {self.year}'
         if self.auxiliary_basis is not None:
             str_ += f', auxiliary_basis: {self.auxiliary_basis}'
         if self.dispersion is not None:
@@ -165,6 +175,8 @@ def simple(self) -> str:
         str_ = self.method
         if self.basis is not None:
             str_ += f'/{self.basis}'
+        if self.year is not None:
+            str_ += f' ({self.year})'
         return str_
 
     def as_dict(self) -> dict:
@@ -196,7 +208,8 @@ def build(self):
                       'solvation_method': None,
                       'solvent': None,
                       'solvation_scheme_level': None,
-                      'args': None}
+                      'args': None,
+                      'year': None}
         allowed_keys = list(level_dict.keys())
 
         if isinstance(self.repr, str):

arc/level_test.py

@@ -119,6 +119,13 @@ def test_build(self):
                          "dlpno-ccsd(t)/def2-tzvp, auxiliary_basis: def2-tzvp/c, solvation_method: smd, "
                          "solvent: water, solvation_scheme_level: 'apfd/def2-tzvp, software: gaussian', software: orca")
 
+    def test_year_validation(self):
+        """Test year validation for Level"""
+        with self.assertRaises(ValueError):
+            Level(method='b97d3', basis='def2tzvp', year=23)
+        level = Level(method='b97d3', basis='def2tzvp', year=2023)
+        self.assertEqual(level.year, 2023)
+
     def test_ess_methods_yml(self):
         """Test reading the ess_methods.yml file"""
         ess_methods = read_yaml_file(path=os.path.join(ARC_PATH, 'data', 'ess_methods.yml'))