adaptive levels: address PR review comments

Copy a no-copy species shared by reactions on different grains (a single
override can't keep both consistent); reject 'inf' as an atom_range
lower bound; fix inner loop variable shadowing, a stale docstring
default, and inverted grain wording in the docs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: alongd

arc/main.py

@@ -1295,9 +1295,11 @@ def process_adaptive_levels(adaptive_levels: list | None) -> dict | None:
                              f'keys, got {entry} which is a {type(entry)} in:\n{adaptive_levels}')
         atom_range = entry['atom_range']
         if not isinstance(atom_range, (list, tuple)) or len(atom_range) != 2 \
-                or not all(isinstance(a, int) or a in ('inf', float('inf')) for a in atom_range):
-            raise InputError(f'The "atom_range" of each adaptive levels entry must be a 2-length list of integers '
-                             f'with an optional "inf" upper bound, got {atom_range} in:\n{adaptive_levels}')
+                or not isinstance(atom_range[0], int) \
+                or not (isinstance(atom_range[1], int) or atom_range[1] in ('inf', float('inf'))):
+            raise InputError(f'The "atom_range" of each adaptive levels entry must be a 2-length list of an integer '
+                             f'lower bound and an integer or "inf" upper bound, got {atom_range} '
+                             f'in:\n{adaptive_levels}')
         atom_range = (atom_range[0], 'inf' if atom_range[1] in ('inf', float('inf')) else atom_range[1])
         levels = entry['levels']
         if not isinstance(levels, dict):

arc/main_test.py

@@ -433,6 +433,11 @@ def test_process_adaptive_levels(self):
         # atom_range is not a 2-length list.
         with self.assertRaises(InputError):
             process_adaptive_levels([{'atom_range': [5], 'levels': {'sp': 'b3lyp/6-311+g(d,p)'}}])
+        # 'inf' is only allowed as the upper bound.
+        with self.assertRaises(InputError):
+            process_adaptive_levels([{'atom_range': [float('inf'), 'inf'], 'levels': {'sp': 'b3lyp/6-311+g(d,p)'}}])
+        with self.assertRaises(InputError):
+            process_adaptive_levels([{'atom_range': ['inf', 10], 'levels': {'sp': 'b3lyp/6-311+g(d,p)'}}])
         # The last range does not end with 'inf'.
         with self.assertRaises(InputError):
             process_adaptive_levels([{'atom_range': [1, 5], 'levels': {'sp': 'wb97xd/def2tzvp'}},

arc/scheduler.py

@@ -3963,19 +3963,21 @@ def _apply_adaptive_reaction_levels(self):
 
         Heavy atoms are conserved across a reaction, so the reaction-wide heavy-atom count (the sum over the reactants,
         equal to the TS supermolecule count) keys a single adaptive level for the whole reaction. A reaction
-        participant whose own heavy-atom count lands it on a *different* adaptive grain than the reaction would
-        otherwise be evaluated at an inconsistent level, mixing levels of theory across the barrier. To avoid this,
-        for each such participant whose ``thermo_at_own_level`` is ``True`` (the default), an autonomous relabeled
-        copy of the species is created from the outset and used by the reaction (evaluated at the reaction-wide
-        level), while the original species is left to compute its own thermochemistry at its own granular level. If
-        ``thermo_at_own_level`` is ``False``, the participant itself is evaluated at the reaction-wide level (no copy).
+        participant whose own heavy-atom count lands it on a *different* (finer) adaptive grain than the reaction
+        would otherwise be evaluated at an inconsistent level, mixing levels of theory across the barrier. To avoid
+        this, each such participant whose ``thermo_at_own_level`` is ``False`` (the default) is itself evaluated at
+        the reaction-wide level (no copy). If ``thermo_at_own_level`` is ``True``, an autonomous relabeled copy of
+        the species is created from the outset and used by the reaction (evaluated at the reaction-wide level),
+        while the original species is left to compute its own thermochemistry at its own granular level. A copy is
+        also created for a no-copy participant that is shared across reactions landing on different grains, since a
+        single per-species override cannot keep both reactions internally consistent.
 
         This runs once during setup, before the reactions are processed, so each reaction is defined with its copies
         from the start (its label, reactants, and products are kept mutually consistent for ``check_attributes`` and
         restart).
         """
-        for i, rxn in enumerate(self.rxn_list):
-            rxn_index = rxn.index if rxn.index is not None else i
+        for rxn_i, rxn in enumerate(self.rxn_list):
+            rxn_index = rxn.index if rxn.index is not None else rxn_i
             reactant_species = [self.species_dict[label] for label in rxn.reactants if label in self.species_dict]
             if len(reactant_species) != len(rxn.reactants) \
                     or any(spc.number_of_heavy_atoms is None for spc in reactant_species):
@@ -3985,24 +3987,30 @@ def _apply_adaptive_reaction_levels(self):
             reaction_n_heavy = sum(spc.number_of_heavy_atoms for spc in reactant_species)
             reaction_range = self._adaptive_atom_range(reaction_n_heavy)
             for participants in (rxn.reactants, rxn.products):
-                for i, label in enumerate(participants):
+                for pos, label in enumerate(participants):
                     spc = self.species_dict.get(label)
                     if spc is None or spc.number_of_heavy_atoms is None \
                             or self._adaptive_atom_range(spc.number_of_heavy_atoms) == reaction_range:
                         continue
                     if not spc.thermo_at_own_level:
-                        spc.adaptive_lot_n_heavy = reaction_n_heavy
-                        continue
+                        if spc.adaptive_lot_n_heavy is None \
+                                or self._adaptive_atom_range(spc.adaptive_lot_n_heavy) == reaction_range:
+                            spc.adaptive_lot_n_heavy = reaction_n_heavy
+                            continue
+                        logger.warning(f'Species {label} participates in reactions on different adaptive level '
+                                       f'grains, creating a dedicated copy of it for reaction {rxn.label} to keep '
+                                       f'the reaction internally consistent.')
                     copy_label = check_label(f'{label}_TS{rxn_index}')[0]
-                    copy_spc = spc.copy()
-                    copy_spc.label = copy_label
-                    copy_spc.adaptive_lot_n_heavy = reaction_n_heavy
-                    copy_spc.compute_thermo = False
-                    copy_spc.include_in_thermo_lib = False
-                    self.species_list.append(copy_spc)
-                    self.species_dict[copy_label] = copy_spc
-                    self.initialize_output_dict(copy_label)
-                    participants[i] = copy_label
+                    if copy_label not in self.species_dict:
+                        copy_spc = spc.copy()
+                        copy_spc.label = copy_label
+                        copy_spc.adaptive_lot_n_heavy = reaction_n_heavy
+                        copy_spc.compute_thermo = False
+                        copy_spc.include_in_thermo_lib = False
+                        self.species_list.append(copy_spc)
+                        self.species_dict[copy_label] = copy_spc
+                        self.initialize_output_dict(copy_label)
+                    participants[pos] = copy_label
             rxn.label = rxn.arrow.join([rxn.plus.join(rxn.reactants), rxn.plus.join(rxn.products)])
 
     def initialize_output_dict(self, label: str | None = None):

arc/scheduler_test.py

@@ -1325,6 +1325,48 @@ def test_thermo_at_own_level_default_no_copy(self):
         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')]

docs/source/advanced.rst

@@ -283,9 +283,9 @@ 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, ``False``) a well that lands on a
-coarser grain than its reaction is evaluated directly at the reaction-wide level, and its
-thermochemistry uses that same (coarser) level. Set ``thermo_at_own_level=True`` on a species
+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.