Show a Level's args in its string form without losing its freq scale factor

`Level.__init__` normalises `args` into both a `keyword` and a `block` slot, so
a keyword-only level (the common case) has an empty `block` slot and
`all(val for val in self.args.values())` is False. `__str__` therefore dropped
args entirely: two levels differing only in args compared equal (`__eq__` is
str-based) while their `as_dict()` differed. The predicate now uses `any()`.

Flipping that predicate alone silently changes a physical quantity.
`assign_frequency_scale_factor()` keys on `str(level)` and returns None on a
miss. All 67 keys in `data/freq_scale_factors.yml` have the form
`method/basis[, solvation_method: ..., solvent: ..., software: ...]`; none
carries args. Once args entered the string, every args-carrying level lost its
scale factor, and since `calc_freq_factor` defaults to True that miss spawns a
full campaign of QM jobs to recompute the factor by Truhlar's method.

The database is keyed on the physical level of theory - method, basis,
dispersion, solvation, software - whereas args are ESS input-file directives
(extra route keywords and input blocks) that the database has never
distinguished. The lookup key is therefore built from a reduced string rather
than from `str(level)`: `get_freq_scale_factor_key()` hands the same key to both
consumers, `assign_frequency_scale_factor()` and
`output._resolve_freq_scale_factor_source()`.

`args` are the only attribute dropped. Everything else the string carries stays
in the key, including attributes the database happens not to use: `dispersion`,
`auxiliary_basis` and `cabs` are part of the model chemistry, and `year` and
`software_version` select a specific parameterisation elsewhere in ARC, so for
all of them "no published factor for this level" is the true answer rather than
a reason to widen the match. Keying on something narrower, such as
`Level.simple()`, would match nothing at all, since every key carries
`software:` and `simple()` omits it.

A level with both arg slots populated missed the database even before this
change and now resolves, consistent with the keyword-only and block-only cases.

The printing loop only ever emitted the `keyword` slot, so a block-only level
would have printed `keyword args: {}` - meaningless output and a broken key.
Every non-empty slot is now printed under its own name.

`utils/scale.py` prints a level as a yaml key for pasting into the database;
that key now comes from the same helper. Its project folder name still derives
from `str(level)`, so levels differing only in args keep separate directories,
but `rename_level()` substituted only `/ * + ( ) space :` and now maps every
remaining character outside `settings['valid_chars']` - the set ARC already
requires of a project name - onto `_`. Args reach that name and can carry
`{ } ' % = \ " $` and backticks, and the name is joined to a path that is passed
to `shutil.rmtree()` and interpolated into double-quoted shell commands.

`__eq__` is str-based, so levels differing only in args no longer compare equal.
Audited: the scheduler's "sp reuses the opt output" shortcut and its
conf_sp/conf_opt comparison now treat args-differing levels as different, which
is the conservative direction - an extra job rather than reusing an output
computed under different directives. Pipe batching is unaffected: `TaskSpec.level`
is a `Level.as_dict()` dict, and the planner compares dicts, not strings.

`as_dict()` is untouched here and still drops keyword-only args, so on its own
this change leaves `__str__` and `as_dict()` asymmetric in the opposite
direction to the one described above. The `as_dict()` predicate is fixed
separately in the branch that preserves args through the as_dict round-trip; the
two are independent and merge cleanly.

Looked for an existing normaliser before adding one: nothing strips args.
`Level.simple()` drops software and solvation, `statmech.arkane._level_to_str()`
builds Arkane `LevelOfTheory` strings, and `scale.rename_level()` only sanitises
a string for folder naming.

Author: calvinp0

arc/level.py

@@ -125,6 +125,18 @@ def __str__(self) -> str:
         """
         Return a humane-readable string representation of the object.
 
+        Returns:
+            str: The level of theory string representation.
+        """
+        return self.string_representation()
+
+    def string_representation(self, include_args: bool = True) -> str:
+        """
+        Return a humane-readable string representation of the object.
+
+        Args:
+            include_args (bool, optional): Whether to include the software-specific ``args``.
+
         Returns:
             str: The level of theory string representation.
         """
@@ -149,12 +161,10 @@ def __str__(self) -> str:
             str_ += f', software: {self.software}'
             if self.software_version is not None:
                 str_ += f', software_version: {self.software_version}'
-        if self.args is not None and self.args and all([val for val in self.args.values()]):
-            if any([key == 'keyword' for key in self.args.keys()]):
-                str_ += ', keyword args:'
-                for key, arg in self.args.items():
-                    if key == 'keyword':
-                        str_ += f' {arg}'
+        if include_args and self.args is not None and any([val for val in self.args.values()]):
+            for key, arg in self.args.items():
+                if arg:
+                    str_ += f', {key} args: {arg}'
         return str_
 
     def copy(self):
@@ -464,6 +474,24 @@ def determine_compatible_ess(self):
                     self.compatible_ess.append(ess)
 
 
+def get_freq_scale_factor_key(level: str | dict | Level) -> str:
+    """
+    Get the key under which a level of theory is stored in ``data/freq_scale_factors.yml``.
+    The key is the level of theory string representation without the software-specific ``args``.
+
+    Args:
+        level (str | dict | Level): The level of theory.
+
+    Returns:
+        str: The frequency scale factor database key.
+    """
+    if isinstance(level, dict):
+        level = Level(repr=level)
+    if isinstance(level, Level):
+        return level.string_representation(include_args=False)
+    return str(level)
+
+
 def assign_frequency_scale_factor(level: str | Level) -> float | None:
     """
     Assign a frequency scaling factor to a level of theory.
@@ -484,8 +512,7 @@ def assign_frequency_scale_factor(level: str | Level) -> float | None:
         except ValueError:
             # A string ARC cannot parse as a level has no scale factor on file.
             return None
-    level_str = str(level)
-    entry = freq_scale_factors.get(level_str)
+    entry = freq_scale_factors.get(get_freq_scale_factor_key(level))
     if entry is not None:
         return entry['factor'] if isinstance(entry, dict) else entry
     return None

arc/level_test.py

@@ -9,7 +9,7 @@
 import unittest
 
 from arc.common import ARC_PATH, read_yaml_file
-from arc.level import Level, assign_frequency_scale_factor
+from arc.level import Level, assign_frequency_scale_factor, get_freq_scale_factor_key
 
 
 class TestLevel(unittest.TestCase):
@@ -235,6 +235,61 @@ def test_str(self):
         self.assertEqual(str(Level(basis='def2svp', compatible_ess=['gaussian', 'terachem'],method='wb97xd',
                                    method_type='dft', software='gaussian')), 'wb97xd/def2svp, software: gaussian')
 
+    def test_str_with_args(self):
+        """Test the __str__() method for levels carrying args."""
+        keyword_level = Level(method='wb97xd', basis='def2tzvp', args={'keyword': {'general': 'IOp(99/33=1)'}})
+        self.assertEqual(str(keyword_level),
+                         "wb97xd/def2tzvp, software: gaussian, keyword args: {'general': 'iop(99/33=1)'}")
+        block_level = Level(method='wb97xd', basis='def2tzvp', args={'block': {'general': '%scf MaxIter 500 end'}})
+        self.assertEqual(str(block_level),
+                         "wb97xd/def2tzvp, software: gaussian, block args: {'general': '%scf maxiter 500 end'}")
+        both_level = Level(method='wb97xd', basis='def2tzvp',
+                           args={'keyword': {'general': 'IOp(99/33=1)'}, 'block': {'general': '%scf MaxIter 500 end'}})
+        self.assertEqual(str(both_level),
+                         "wb97xd/def2tzvp, software: gaussian, keyword args: {'general': 'iop(99/33=1)'}, "
+                         "block args: {'general': '%scf maxiter 500 end'}")
+        self.assertNotEqual(keyword_level, block_level)
+        self.assertNotEqual(keyword_level, Level(method='wb97xd', basis='def2tzvp'))
+
+    def test_str_keeps_year_and_software_version(self):
+        """Test that __str__() retains the year and the software_version."""
+        self.assertEqual(str(Level(method='wb97xd', basis='def2tzvp', year=2023)),
+                         'wb97xd/def2tzvp, year: 2023, software: gaussian')
+        self.assertEqual(str(Level(method='wb97xd', basis='def2tzvp', software_version=16)),
+                         'wb97xd/def2tzvp, software: gaussian, software_version: 16')
+        self.assertNotEqual(Level(method='wb97xd', basis='def2tzvp', year=2023),
+                            Level(method='wb97xd', basis='def2tzvp'))
+        self.assertNotEqual(Level(method='wb97xd', basis='def2tzvp', software_version=16),
+                            Level(method='wb97xd', basis='def2tzvp'))
+
+    def test_get_freq_scale_factor_key(self):
+        """Test the get_freq_scale_factor_key() function."""
+        key = 'wb97xd/def2tzvp, software: gaussian'
+        self.assertEqual(get_freq_scale_factor_key(key), key)
+        self.assertEqual(get_freq_scale_factor_key(Level(method='wb97xd', basis='def2tzvp')), key)
+        self.assertEqual(get_freq_scale_factor_key(Level(method='wb97xd', basis='def2tzvp',
+                                                         args={'keyword': {'general': 'IOp(99/33=1)'}})), key)
+        self.assertEqual(get_freq_scale_factor_key(Level(method='wb97xd', basis='def2tzvp',
+                                                         args={'block': {'general': '%scf MaxIter 500 end'}})), key)
+        self.assertEqual(get_freq_scale_factor_key({'method': 'wb97xd', 'basis': 'def2tzvp',
+                                                    'args': {'keyword': {'general': 'IOp(99/33=1)'}}}), key)
+        self.assertEqual(get_freq_scale_factor_key(Level(method='wb97xd', basis='def2tzvp', solvation_method='smd',
+                                                         solvent='water',
+                                                         args={'keyword': {'general': 'IOp(99/33=1)'}})),
+                         'wb97xd/def2tzvp, solvation_method: smd, solvent: water, software: gaussian')
+
+    def test_get_freq_scale_factor_key_keeps_the_level_identity(self):
+        """Test that get_freq_scale_factor_key() retains every attribute other than args."""
+        self.assertEqual(get_freq_scale_factor_key(Level(method='b3lyp', basis='def2tzvp', dispersion='gd3bj')),
+                         'b3lyp/def2tzvp, dispersion: gd3bj, software: gaussian')
+        self.assertEqual(get_freq_scale_factor_key(Level(method='dlpno-ccsd(t)', basis='def2-tzvp',
+                                                         auxiliary_basis='def2-tzvp/c')),
+                         'dlpno-ccsd(t)/def2-tzvp, auxiliary_basis: def2-tzvp/c, software: orca')
+        self.assertEqual(get_freq_scale_factor_key(Level(method='wb97xd', basis='def2tzvp', year=2023,
+                                                         software_version=16,
+                                                         args={'keyword': {'general': 'IOp(99/33=1)'}})),
+                         'wb97xd/def2tzvp, year: 2023, software: gaussian, software_version: 16')
+
     def test_assign_frequency_scale_factor(self):
         """Test the assign_frequency_scale_factor() method."""
         self.assertEqual(assign_frequency_scale_factor(Level(method='CCSD(T)', basis='cc-pvtz')), 0.975)
@@ -256,6 +311,18 @@ def test_assign_frequency_scale_factor_from_str(self):
             with self.assertRaises(ValueError):
                 Level(repr=repr_)
 
+    def test_assign_frequency_scale_factor_with_args(self):
+        """Test that assign_frequency_scale_factor() resolves for levels carrying args."""
+        self.assertEqual(assign_frequency_scale_factor(
+            Level(method='wb97xd', basis='Def2TZVP', args={'keyword': {'general': 'IOp(99/33=1)'}})), 0.988)
+        self.assertEqual(assign_frequency_scale_factor(
+            Level(method='wb97xd', basis='Def2TZVP', args={'block': {'general': '%scf MaxIter 500 end'}})), 0.988)
+        self.assertEqual(assign_frequency_scale_factor(
+            Level(method='wb97xd', basis='Def2TZVP', args={'keyword': {'general': 'IOp(99/33=1)'},
+                                                           'block': {'general': '%scf MaxIter 500 end'}})), 0.988)
+        self.assertEqual(assign_frequency_scale_factor(
+            Level(method='CBS-QB3', args={'keyword': {'general': 'IOp(99/33=1)'}})), 1.004)
+
 
 if __name__ == '__main__':
     unittest.main(testRunner=unittest.TextTestRunner(verbosity=2))

arc/output.py

@@ -19,6 +19,7 @@
 from arc.imports import settings
 from arc.job.env_run import rmg_env_command
 from arc.job.local import execute_command
+from arc.level import get_freq_scale_factor_key
 from arc.parser.parser import parse_1d_scan_energies, parse_e_elect, parse_ess_version, parse_opt_steps, parse_zpe_correction
 from arc.species.converter import xyz_to_str
 from arc.statmech.arkane import (
@@ -188,8 +189,7 @@ def _resolve_freq_scale_factor_source(freq_level) -> str | None:
 
     sources = data.get('sources', {})
     factors = data.get('freq_scale_factors', {})
-    level_key = str(freq_level) if not isinstance(freq_level, str) else freq_level
-    entry = factors.get(level_key)
+    entry = factors.get(get_freq_scale_factor_key(freq_level))
     if not isinstance(entry, dict):
         return None
     source_key = entry.get('source')

arc/output_test.py

@@ -96,6 +96,14 @@ def test_known_level_returns_citation(self):
         self.assertIsNotNone(result)
         self.assertIn('10.1021/ct100326h', result)
 
+    def test_known_level_with_args_returns_citation(self):
+        """A level carrying args should resolve to the same citation as the same level without args."""
+        level = Level(method='wb97xd', basis='def2tzvp', software='gaussian',
+                      args={'keyword': {'general': 'IOp(99/33=1)'}})
+        result = _resolve_freq_scale_factor_source(level)
+        self.assertIsNotNone(result)
+        self.assertIn('10.1021/ct100326h', result)
+
 
 class TestParseThermoDataBlock(unittest.TestCase):
     """Tests for parse_thermo_data_block in arkane.py."""

arc/utils/scale.py

@@ -17,7 +17,8 @@
                         initialize_log,
                         time_lapse,
                         )
-from arc.level import Level
+from arc.imports import settings
+from arc.level import Level, get_freq_scale_factor_key
 from arc.parser.parser import parse_zpe_correction
 from arc.scheduler import Scheduler
 from arc.species.species import ARCSpecies
@@ -30,6 +31,8 @@
 
 logger = get_logger()
 
+valid_chars = settings['valid_chars']
+
 HEADER = 'FREQ: A PROGRAM FOR OPTIMIZING SCALE FACTORS (Version 1)\n'\
          '                 written by                 \n'\
          'Haoyu S. Yu, Lucas J. Fiedler, I.M. Alecu, and Donald G. Truhlar\n'\
@@ -241,7 +244,8 @@ def summarize_results(lambda_zpes: list,
             text += f'(execution time: {execution_time})\n'
             logger.info(text)
             f.write(text)
-            database_formats.append(f"""  '{level}': {harmonic_freq_scaling_factor:.3f},  # [4]\n""")
+            database_formats.append(
+                f"""  '{get_freq_scale_factor_key(level)}': {harmonic_freq_scaling_factor:.3f},  # [4]\n""")
         logger.info(database_text)
         f.write(database_text)
         for database_format in database_formats:
@@ -355,4 +359,4 @@ def rename_level(level: str) -> str:
     level = level.replace(')', 'b')
     level = level.replace(' ', '_')
     level = level.replace(':', '..')
-    return level
+    return ''.join([char if char in valid_chars else '_' for char in level])

arc/utils/scale_test.py

@@ -15,6 +15,7 @@
                              get_species_list,
                              rename_level,
                              summarize_results,
+                             valid_chars,
                              )
 
 
@@ -120,6 +121,17 @@ def test_rename_level(self):
         self.assertEqual(renamed_level2, 'wb97xd_6-311pGb2d,2pb')
         self.assertEqual(renamed_level3, 'wb97xd_aug-ccpZQZ,_solvation_method.._SMD,_solvent.._DMSO,_software.._gaussian')
 
+    def test_rename_level_sanitizes_args(self):
+        """Test that rename_level() maps the characters an args-carrying level contributes onto valid ones."""
+        level = Level(method='wb97xd', basis='def2tzvp', software='orca',
+                      args={'block': {'general': '%scf\nMaxIter 500\nend'}})
+        renamed_level = rename_level(str(level))
+        for char in renamed_level:
+            self.assertIn(char, valid_chars)
+        self.assertNotIn(os.sep, renamed_level)
+        self.assertEqual(rename_level("a/b, keyword args: {'general': '$(rm -rf ~)'}"),
+                         'a_b,_keyword_args..___general_..___brm_-rf__b__')
+
     @classmethod
     def tearDownClass(cls):
         """