species: default thermo_at_own_level to False

Reaction wells take the reaction-wide level directly by default (no relabeled copies, no duplicated jobs); set True per species to opt into its own granular level for thermo.

Author: alongd

arc/scheduler_test.py

@@ -1317,9 +1317,11 @@ def build_scheduler(self, rxn, species_list, name):
                          testing=True)
 
     def test_bimolecular_creates_copies(self):
-        """Test that a reaction with wells on a different grain than the reaction gets relabeled copies"""
-        r = [ARCSpecies(label='CH4', smiles='C'), ARCSpecies(label='OH', smiles='[OH]')]
-        p = [ARCSpecies(label='CH3', smiles='[CH3]'), ARCSpecies(label='H2O', smiles='O')]
+        """Test that with thermo_at_own_level=True, wells on a different grain get relabeled copies"""
+        r = [ARCSpecies(label='CH4', smiles='C', thermo_at_own_level=True),
+             ARCSpecies(label='OH', smiles='[OH]', thermo_at_own_level=True)]
+        p = [ARCSpecies(label='CH3', smiles='[CH3]', thermo_at_own_level=True),
+             ARCSpecies(label='H2O', smiles='O', thermo_at_own_level=True)]
         rxn = ARCReaction(label='CH4 + OH <=> CH3 + H2O', r_species=r, p_species=p)
         sched = self.build_scheduler(rxn, r + p, 'adaptive_bimol')
 
@@ -1347,19 +1349,59 @@ def test_bimolecular_creates_copies(self):
             self.assertIsNone(original.adaptive_lot_n_heavy)
             self.assertTrue(original.compute_thermo)
 
-    def test_thermo_at_own_level_false_no_copy(self):
-        """Test that with thermo_at_own_level=False the species itself takes the reaction-wide level, with no copy"""
-        r = [ARCSpecies(label='CH4', smiles='C', thermo_at_own_level=False),
-             ARCSpecies(label='OH', smiles='[OH]', thermo_at_own_level=False)]
-        p = [ARCSpecies(label='CH3', smiles='[CH3]', thermo_at_own_level=False),
-             ARCSpecies(label='H2O', smiles='O', thermo_at_own_level=False)]
+    def test_thermo_at_own_level_default_no_copy(self):
+        """Test that by default (thermo_at_own_level=False) the species itself takes the reaction-wide level, no copy"""
+        r = [ARCSpecies(label='CH4', smiles='C'), ARCSpecies(label='OH', smiles='[OH]')]
+        p = [ARCSpecies(label='CH3', smiles='[CH3]'), ARCSpecies(label='H2O', smiles='O')]
         rxn = ARCReaction(label='CH4 + OH <=> CH3 + H2O', r_species=r, p_species=p)
-        sched = self.build_scheduler(rxn, r + p, 'adaptive_noflag')
+        sched = self.build_scheduler(rxn, r + p, 'adaptive_default')
 
         self.assertEqual(rxn.label, 'CH4 + OH <=> CH3 + H2O')
         self.assertFalse(any('_TS' in label for label in sched.species_dict))
         self.assertEqual(sched.species_dict['CH4'].adaptive_lot_n_heavy, 2)
 
+    def test_shared_species_across_grains_gets_copy(self):
+        """Test that a no-copy species shared by reactions on different grains gets a copy for the second reaction"""
+        oh = ARCSpecies(label='OH', smiles='[OH]')
+        h2o = ARCSpecies(label='H2O', smiles='O')
+        rxn1 = ARCReaction(label='CH4 + OH <=> CH3 + H2O',
+                           r_species=[ARCSpecies(label='CH4', smiles='C'), oh],
+                           p_species=[ARCSpecies(label='CH3', smiles='[CH3]'), h2o])
+        rxn2 = ARCReaction(label='C3H8 + OH <=> nC3H7 + H2O',
+                           r_species=[ARCSpecies(label='C3H8', smiles='CCC'), oh],
+                           p_species=[ARCSpecies(label='nC3H7', smiles='[CH2]CC'), h2o])
+        project_directory = os.path.join(ARC_PATH, 'Projects', 'adaptive_shared_delete')
+        self.addCleanup(shutil.rmtree, project_directory, ignore_errors=True)
+        species_list = rxn1.r_species + rxn1.p_species + [rxn2.r_species[0], rxn2.p_species[0]]
+        sched = Scheduler(project='adaptive_shared',
+                          ess_settings=self.ess_settings,
+                          species_list=species_list,
+                          rxn_list=[rxn1, rxn2],
+                          opt_level=Level(repr='b3lyp/6-31g(d,p)'),
+                          sp_level=Level(repr='b3lyp/6-311+g(d,p)'),
+                          freq_level=Level(repr='b3lyp/6-31g(d,p)'),
+                          adaptive_levels={(1, 1): {('sp',): Level(repr='ccsd(t)-f12/cc-pvtz-f12')},
+                                           (2, 3): {('sp',): Level(repr='dlpno-ccsd(t)/def2-tzvp')},
+                                           (4, 'inf'): {('sp',): Level(repr='b3lyp/6-311+g(d,p)')}},
+                          project_directory=project_directory,
+                          job_types=initialize_job_types(),
+                          testing=True)
+
+        # rxn1 (2 heavy atoms) set the shared wells' overrides; rxn1 itself is unchanged.
+        self.assertEqual(rxn1.label, 'CH4 + OH <=> CH3 + H2O')
+        self.assertEqual(sched.species_dict['OH'].adaptive_lot_n_heavy, 2)
+        # rxn2 (4 heavy atoms) lands on a different grain, so the shared wells got dedicated copies.
+        self.assertEqual(set(rxn2.reactants), {'C3H8', 'OH_TS1'})
+        self.assertEqual(set(rxn2.products), {'nC3H7', 'H2O_TS1'})
+        self.assertEqual(rxn2.label,
+                         rxn2.arrow.join([rxn2.plus.join(rxn2.reactants), rxn2.plus.join(rxn2.products)]))
+        for copy_label in ['OH_TS1', 'H2O_TS1']:
+            self.assertEqual(sched.species_dict[copy_label].adaptive_lot_n_heavy, 4)
+            self.assertFalse(sched.species_dict[copy_label].compute_thermo)
+        # Unshared rxn2 wells just took the rxn2 override, no copies.
+        self.assertEqual(sched.species_dict['C3H8'].adaptive_lot_n_heavy, 4)
+        self.assertEqual(sched.species_dict['nC3H7'].adaptive_lot_n_heavy, 4)
+
     def test_unimolecular_no_copy(self):
         """Test that a reaction whose well shares the reaction's grain gets no copies"""
         r = [ARCSpecies(label='nC3H7', smiles='[CH2]CC')]

arc/species/species.py

@@ -109,10 +109,10 @@ class ARCSpecies(object):
         bond_corrections (dict, optional): The bond additivity corrections (BAC) to be used. Determined from the
                                            structure if not directly given.
         compute_thermo (bool, optional): Whether to calculate thermodynamic properties for this species.
-        thermo_at_own_level (bool, optional): Relevant only when ``adaptive_levels`` are used. If ``True`` (default),
-            the species' thermochemistry is computed at its own size-appropriate (granular) adaptive level even when
-            it participates in a reaction; the reaction's energetics then use a separate relabeled copy of the species
-            evaluated at the reaction-consistent level. If ``False``, the species itself is evaluated at the
+        thermo_at_own_level (bool, optional): Relevant only when ``adaptive_levels`` are used. If ``True``, the
+            species' thermochemistry is computed at its own size-appropriate (granular) adaptive level even when it
+            participates in a reaction; the reaction's energetics then use a separate relabeled copy of the species
+            evaluated at the reaction-consistent level. If ``False`` (default), the species itself is evaluated at the
             reaction-consistent (coarser) level and no copy is made.
         include_in_thermo_lib (bool, optional): Whether to include in the output RMG library.
         e0_only (bool, optional): Whether to only run statmech (w/o thermo) to compute E0.
@@ -317,7 +317,7 @@ def __init__(self,
                  charge: int | None = None,
                  checkfile: str | None = None,
                  compute_thermo: bool | None = None,
-                 thermo_at_own_level: bool = True,
+                 thermo_at_own_level: bool = False,
                  adaptive_lot_n_heavy: int | None = None,
                  include_in_thermo_lib: bool | None = True,
                  consider_all_diastereomers: bool = True,
@@ -702,7 +702,7 @@ def as_dict(self,
             species_dict['charge'] = self.charge
         if not self.compute_thermo and not self.is_ts:
             species_dict['compute_thermo'] = self.compute_thermo
-        if not self.thermo_at_own_level:
+        if self.thermo_at_own_level:
             species_dict['thermo_at_own_level'] = self.thermo_at_own_level
         if self.adaptive_lot_n_heavy is not None:
             species_dict['adaptive_lot_n_heavy'] = self.adaptive_lot_n_heavy
@@ -902,7 +902,7 @@ def from_dict(self, species_dict):
         self.multi_species = species_dict['multi_species'] if 'multi_species' in species_dict else None
         self.charge = species_dict['charge'] if 'charge' in species_dict else 0
         self.compute_thermo = species_dict['compute_thermo'] if 'compute_thermo' in species_dict else not self.is_ts
-        self.thermo_at_own_level = species_dict['thermo_at_own_level'] if 'thermo_at_own_level' in species_dict else True
+        self.thermo_at_own_level = species_dict['thermo_at_own_level'] if 'thermo_at_own_level' in species_dict else False
         self.adaptive_lot_n_heavy = species_dict['adaptive_lot_n_heavy'] if 'adaptive_lot_n_heavy' in species_dict else None
         self.include_in_thermo_lib = species_dict['include_in_thermo_lib'] if 'include_in_thermo_lib' in species_dict else True
         self.e0_only = species_dict['e0_only'] if 'e0_only' in species_dict else False

arc/species/species_test.py

@@ -610,22 +610,22 @@ def test_as_dict(self):
 
     def test_thermo_at_own_level_round_trip(self):
         """Test that thermo_at_own_level and adaptive_lot_n_heavy round-trip through as_dict/from_dict"""
-        # Defaults: not serialized, restored to True / None.
+        # Defaults: not serialized, restored to False / None.
         default_spc = ARCSpecies(label='ethane', smiles='CC')
         default_dict = default_spc.as_dict()
         self.assertNotIn('thermo_at_own_level', default_dict)
         self.assertNotIn('adaptive_lot_n_heavy', default_dict)
         restored_default = ARCSpecies(species_dict=default_dict)
-        self.assertTrue(restored_default.thermo_at_own_level)
+        self.assertFalse(restored_default.thermo_at_own_level)
         self.assertIsNone(restored_default.adaptive_lot_n_heavy)
 
         # Non-default values: serialized and restored.
-        spc = ARCSpecies(label='ethane', smiles='CC', thermo_at_own_level=False, adaptive_lot_n_heavy=8)
+        spc = ARCSpecies(label='ethane', smiles='CC', thermo_at_own_level=True, adaptive_lot_n_heavy=8)
         spc_dict = spc.as_dict()
-        self.assertFalse(spc_dict['thermo_at_own_level'])
+        self.assertTrue(spc_dict['thermo_at_own_level'])
         self.assertEqual(spc_dict['adaptive_lot_n_heavy'], 8)
         restored = ARCSpecies(species_dict=spc_dict)
-        self.assertFalse(restored.thermo_at_own_level)
+        self.assertTrue(restored.thermo_at_own_level)
         self.assertEqual(restored.adaptive_lot_n_heavy, 8)
 
     def test_from_dict(self):

docs/source/advanced.rst

@@ -252,9 +252,10 @@ Adaptive levels of theory
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 ARC allows users to adapt the level of theory to the size of the molecule.
 To do so, pass the ``adaptive_levels`` attribute, which is a list of entries.
-Each entry is a dictionary with an ``atom_range`` 2-list giving the heavy
-(non-hydrogen) atom count range (the upper bound may be ``inf``), and a ``levels``
-mapping from job type to the respective level of theory (a string or a dictionary).
+Each entry is a dictionary with two keys: ``atom_range``, a two-element list ``[min, max]``
+giving the species' size as a range of heavy (non-hydrogen) atom counts (the upper bound of
+the last range must be ``inf``); and ``levels``, a mapping from job type(s) to the level of
+theory (a string or a dictionary) to use for that size range.
 Job types that share a level may be given as a single whitespace- or comma-separated
 key (e.g. ``opt freq``). Don't forget to bound the entire range between 1 and
 ``inf``, and make sure there aren't any gaps in the heavy atom ranges. For example::
@@ -283,12 +284,12 @@ levels (defined separately, e.g., via ``opt_level``, or using ARC's defaults).
 When a species participates in a reaction, all of the reaction's species (the TS and the
 reactant/product wells) are energy-evaluated at a single, reaction-consistent level keyed
 by the largest participant (the TS), so the barrier is computed at one consistent level.
-By default (the per-species ``thermo_at_own_level`` flag, ``True``) each species'
-thermochemistry is still computed at its own size-appropriate (granular) adaptive level: an
-autonomous, relabeled copy of any well that lands on a coarser grain than its reaction is
-created and used by the reaction (at the reaction-wide level), while the original species
-keeps its own level for thermochemistry. Set ``thermo_at_own_level=False`` on a species to
-have it evaluated at the reaction-wide level directly (no copy, coarser thermochemistry).
+By default (the per-species ``thermo_at_own_level`` flag, ``False``) a well whose own size
+falls on a finer grain than its reaction's is evaluated directly at the reaction-wide
+(coarser) level, and its thermochemistry uses that same level. Set ``thermo_at_own_level=True`` on a species
+to instead compute its thermochemistry at its own size-appropriate (granular) adaptive level:
+an autonomous, relabeled copy of the species is then created and used by the reaction (at the
+reaction-wide level), while the original keeps its own level for thermochemistry.
 
 
 Control job memory allocation