DO NOT MERGE (draft): PDep→QM network selection and hybrid Arkane input generation (I-008)

.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,6 +84,10 @@ 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.
     ME_methods: ['CSE', 'MSC']  # master equation methods for PES SA,
                                 # any combination of 'CSE', 'RS', 'MSC', default: ['CSE', 'MSC']
     top_SA_species: 10  # optional, used per observable to determine thermo to calculate, default: 10

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],
                               ):

t3/pdep/__init__.py

@@ -0,0 +1,97 @@
+"""
+t3 pdep module
+
+Deciding which pressure-dependent reaction networks deserve expensive QM refinement, and
+parsing the RMG network files that decision is based on.
+"""
+
+from t3.pdep.api import (
+    load_pdep_budget_record,
+    load_pdep_exploration_results,
+    load_pdep_network_assessments,
+    load_pdep_network_selections,
+    rank_pdep_networks,
+    save_pdep_budget_record,
+    save_pdep_exploration_results,
+    save_pdep_network_assessments,
+    save_pdep_network_selections,
+    select_pdep_network,
+)
+from t3.pdep.budget import (
+    BUDGET_ALGORITHM_VERSION,
+    BUDGET_OUTCOME_ADMITTED,
+    BUDGET_OUTCOME_REFUSED,
+    BUDGET_RECORD_FILE_NAME,
+    BUDGET_RECORD_SCHEMA_VERSION,
+    BUDGET_SKIP_DOES_NOT_FIT_REMAINING,
+    BUDGET_SKIP_EXCEEDS_BUDGET,
+    BUDGET_SKIP_MAX_NETWORKS_REACHED,
+    BUDGET_SKIP_NOT_EVALUATED,
+    PDepBudgetNetworkOutcome,
+    PDepBudgetRecord,
+    VALID_BUDGET_OUTCOMES,
+    VALID_BUDGET_SKIP_REASON_CODES,
+    apply_pdep_qm_budget,
+    budget_record_path,
+    build_pdep_budget_record,
+)
+from t3.pdep.cache import (
+    SA_CACHE_CONTRACT_VERSION,
+    sa_cache_metadata_path,
+    validate_sa_cache,
+    write_sa_cache_metadata,
+)
+from t3.pdep.hybrid import (
+    HybridNetworkResult,
+    QMEnergySettings,
+    write_hybrid_network_input_file,
+)
+from t3.pdep.mesolver import (
+    ArkaneMESolverAdapter,
+    MESolverAdapter,
+    mesolver_factory,
+    register_mesolver_adapter,
+)
+from t3.pdep.parser import (
+    PDepNetwork,
+    PDepPathReaction,
+    parse_pdep_network_file,
+    parse_pdep_network_text,
+)
+from t3.pdep.selector import (
+    CACHE_STATUS_CACHED_REJECTED,
+    CACHE_STATUS_CACHED_VALID,
+    CACHE_STATUS_GENERATED,
+    CACHE_STATUS_UNVALIDATED,
+    DEFAULT_MIN_DELTA_LN_K,
+    E0_PERTURBATION_J_PER_MOL,
+    EVALUATION_STATUS_EVALUATED,
+    EVALUATION_STATUS_NOT_EVALUATED,
+    PDepNetworkSelection,
+    SELECTION_ALGORITHM_VERSION,
+    SELECTION_SCHEMA_VERSION,
+    SensitiveTransitionState,
+    coefficient_floor,
+    resolve_direction_key,
+    select_from_sa_dict,
+    select_from_sa_dict_with_diagnostics,
+    select_sensitive_wells,
+)
+from t3.pdep.assessment import (
+    ASSESSMENT_RECORD_FILE_NAME,
+    ASSESSMENT_RECORD_SCHEMA_VERSION,
+    PDepNetworkAssessment,
+    assessments_record_path,
+)
+from t3.pdep.reason_codes import (
+    INTERNAL_ERROR_REASON_CODES,
+    PRE_SELECTOR_REASON_CODES,
+    REASON_CODE_STATUS,
+    SELECTION_BEARING_REASON_CODES,
+    STATUS_EVALUATED_NEGATIVE,
+    STATUS_INTERNAL_ERROR,
+    STATUS_NOT_EVALUATED,
+    STATUS_QUALIFIED,
+    VALID_ASSESSMENT_REASON_CODES,
+    VALID_ASSESSMENT_STATUSES,
+)