Merge pull request #179 from ReactionMechanismGenerator/pdep_qm

PDep→QM network selection and hybrid Arkane input generation (I-008)

Author: alongd

.gitignore

@@ -152,3 +152,24 @@ htmlcov/*
 
 # Local-only agent working files (never commit)
 docs/superpowers/
+docs/t3-pdep-qm-scope.md
+docs/t3-pdep-qm-impl-plan.md
+docs/t3-pdep-qm-next-session-prompt.md
+docs/t3-pdep-qm-explorer-design.md
+
+# Vendored test fixtures are real Arkane output and must be tracked, despite the *.log rule
+# above which exists to keep run logs out of the repo.
+!tests/data/pdep_arkane_log/*.log
+# Narrowed to the exact file name, not just the depth: a `*/*.log` negation would also un-ignore
+# any other log that happened to land in a network's fixture directory (e.g. a stray debug.log
+# from a local run), which is the accidental-commit risk the *.log rule exists to prevent.
+!tests/data/pdep_real_networks/*/arkane.log
+
+# Artifacts a test run writes into the tracked fixture trees. Some tests point a real T3 at a
+# fixture iteration directory, and T3 writes its per-iteration records where it always does. Named
+# exactly, and only under the two fixture directories that are actually written to, so this cannot
+# hide a record that was meant to be a fixture.
+tests/data/minimal_data/iteration_1/t3_pdep_qm_budget.yml
+tests/data/minimal_data/iteration_1/t3_pdep_network_assessments.yml
+tests/data/pdep_network/iteration_1/t3_pdep_qm_budget.yml
+tests/data/pdep_network/iteration_1/t3_pdep_network_assessments.yml

docs/input_reference.md

@@ -84,8 +84,22 @@ t3:
     pdep_SA_threshold: 0.001  # optional, used to determine wells and reactions to calculate thermo
                               # and rates for from a PES of a sensitive reaction, default: 0.001
                               # Pass None to skip PES SA.
+    pdep_min_delta_ln_k: 0.001  # optional, the smallest ln(k) response to a PES SA perturbation that
+                                # still counts as "sensitive", default: 0.001. Acts as an absolute
+                                # floor alongside the relative pdep_SA_threshold, so that denormal
+                                # near-zero sensitivity coefficients cannot pass on relative grounds.
+    pdep_QM_max_transition_states: 10  # optional, per-iteration budget of uncertain transition
+                                       # states admitted to QM across all selected PDep networks
+                                       # (networks are admitted most-deserving-first, and a network
+                                       # is admitted whole or not at all), default: None (unlimited).
+                                       # Must be a positive integer when given; booleans are refused.
+    pdep_QM_max_networks: 3  # optional, per-iteration cap on the number of PDep networks admitted
+                             # to QM, default: None (unlimited). Must be a positive integer when
+                             # given; booleans are refused.
     ME_methods: ['CSE', 'MSC']  # master equation methods for PES SA,
-                                # any combination of 'CSE', 'RS', 'MSC', default: ['CSE', 'MSC']
+                                # any combination of 'CSE', 'RS', 'MSC', default: ['CSE', 'MSC'].
+                                # Case-insensitive; entries are normalized to upper case, which is
+                                # the spelling used for the per-method output sub-directory.
     top_SA_species: 10  # optional, used per observable to determine thermo to calculate, default: 10
     top_SA_reactions: 10  # optional, used per observable to determine rates to calculate as well as
                           # thermo of species participating in these reactions, default: 10

t3/common.py

@@ -22,6 +22,17 @@
 PROJECTS_BASE_PATH = os.path.join(t3_path, 'Projects')
 VALID_CHARS = "-_=.,%s%s" % (string.ascii_letters, string.digits)
 
+# The master-equation methods T3 knows how to ask Arkane for, mapping the shorthand a user writes
+# in ``T3.sensitivity.ME_methods`` to Arkane's own name for it. It lives here rather than beside
+# its main consumer in ``t3.utils.writer`` because ``t3.schema`` validates against it, and schema
+# validation must not drag in the writer's dependency stack (Mako, ARC species perception, the
+# thermo reader). ``t3.utils.writer`` re-exports it, so the many existing
+# ``from t3.utils.writer import METHOD_MAP`` call sites keep working.
+METHOD_MAP = {'CSE': 'chemically-significant eigenvalues',
+              'RS': 'reservoir state',
+              'MSC': 'modified strong collision',
+              }
+
 
 def get_species_by_label(label: str,
                          species_list: list[ARCSpecies],

t3/logger.py

@@ -213,6 +213,34 @@ def log_species_summary(self,
             self.log(f'{key}: {species.qm_label}{smiles} '
                      f'(status: {clean_t3_status(species)})')
 
+    def log_pdep_network_summary(self,
+                                 selections: list,
+                                 ):
+        """
+        Log a summary of the PDep network QM-selection decisions.
+
+        Args:
+            selections (list): The ``PDepNetworkSelection`` decisions to summarize.
+        """
+        self.log('\n\n\nPDep Network Summary:\n'
+                 '---------------------')
+        qualifying = [selection for selection in selections if selection.qualified]
+        if not qualifying:
+            self.log('No PDep networks qualified for QM refinement.')
+            return
+        for selection in qualifying:
+            strongest = max(selection.uncertain_path_reactions,
+                            key=lambda ts: ts.delta_ln_k,
+                            default=None)
+            evidence = ''
+            if strongest is not None:
+                comment = strongest.kinetics_comment.splitlines()[0] if strongest.kinetics_comment else ''
+                via = f' via {strongest.path_reaction_str}' if strongest.path_reaction_str else ''
+                kinetics = f', kinetics: {comment}' if comment else ''
+                evidence = (f' (strongest evidence: TS {strongest.ts_label}{via}, '
+                           f'delta_ln_k={strongest.delta_ln_k:.3g} at {strongest.condition}{kinetics})')
+            self.log(f'{selection.network_id}: {selection.reason()}{evidence}')
+
     def log_reactions_summary(self,
                               reactions_dict: dict[int, T3Reaction],
                               ):