docs(perception): Revise chemical perception documentation for clarity and structure, enhancing the overview and detailing each processing pass

Author: TKanX

docs/02_perception.md

@@ -1,105 +1,88 @@
-# Phase 1: Chemical Perception
+# Phase 1: Chemical Perception Overview
 
-Chemical perception starts with nothing more than `MolecularGraph` connectivity and ends with an `AnnotatedMolecule` packed with ring membership, Kekulé-expanded bonds, formal charges, conjugation flags, and hybridization. Every later phase (typing + topology building) simply reads the data created here, so correctness and determinism are critical.
+Chemical perception is the first stage in the `dreid-typer` pipeline. It transforms a minimal `MolecularGraph` (atoms + bonds) into an `AnnotatedMolecule`, a chemically-aware structure that records every property the typing and builder phases require. The orchestrator is `perception::perceive`, which executes six deterministic passes in a fixed order.
 
-## The Ordered Pipeline
-
-`perception::perceive` executes six passes in a fixed order. Each pass depends on the artefacts emitted by the preceding one.
+## Pipeline Overview
 
 ```mermaid
 graph TD
-  A["<b>MolecularGraph</b>"] --> B("1. Rings<br /><code>rings::perceive</code>")
-  B --> C("2. Kekulization<br /><code>kekulize::perceive</code>")
-  C --> D("3. Electron Heuristics<br /><code>electrons::perceive</code>")
-  D --> E("4. Aromaticity<br /><code>aromaticity::perceive</code>")
-  E --> F("5. Resonance Mapping<br /><code>resonance::perceive</code>")
-  F --> G("6. Hybridization<br /><code>hybridization::perceive</code>")
-  G --> H["<b>AnnotatedMolecule</b>"]
+    subgraph Input
+        A["<b>MolecularGraph</b><br><i>Connectivity only</i>"]
+    end
+
+    subgraph "Chemical Perception (perception::perceive)"
+        RINGS["1. Rings<br><code>rings::perceive</code>"]
+        KEK["2. Kekulé Expansion<br><code>kekulize::perceive</code>"]
+        ELECTRONS["3. Electron Assignments<br><code>electrons::perceive</code>"]
+        AROMA["4. Aromaticity<br><code>aromaticity::perceive</code>"]
+        RESON["5. Resonance<br><code>resonance::perceive</code>"]
+        HYBRID["6. Hybridization<br><code>hybridization::perceive</code>"]
+    end
+
+    subgraph Output
+        OUT["<b>AnnotatedMolecule</b><br><i>Ring + electronic context</i>"]
+    end
+
+    A --> RINGS --> KEK --> ELECTRONS --> AROMA --> RESON --> HYBRID --> OUT
 ```
 
-- **Rings** discover the Smallest Set of Smallest Rings (SSSR) so that later passes know which atoms are cyclic and what the smallest ring size is.
-- **Kekulization** rewrites every aromatic bond into an explicit single/double assignment that satisfies valence limits.
-- **Electron heuristics** assign formal charges, lone pairs, and special-case templates for nitro, sulfonyl, halogen oxyanions, etc.
-- **Aromaticity** applies Hückel counting to each ring system and records whether atoms are aromatic or anti-aromatic.
-- **Resonance** leverages the `pauling` crate plus local heuristics to mark conjugated atoms and damp unrealistic resonance participation (e.g., sulfate oxygens).
-- **Hybridization** collapses degrees + lone pairs into a final hybridization label, with special handling for conjugated or aromatic atoms.
-
-The rest of this document dives into each pass.
-
-## Step 1 – Ring System Perception (`rings::perceive`)
-
-The first task is topological: determine which atoms reside in rings. The algorithm computes the cyclomatic number to short-circuit acyclic graphs, then enumerates candidate cycles by temporarily removing each bond and finding a shortest path between its endpoints. From this candidate list the code selects a minimal cycle basis via Gaussian elimination over GF(2), producing an SSSR set.
-
-For every atom in a detected ring the annotator sets `is_in_ring = true` and stores the smallest ring size observed. These flags are prerequisites for Kekulé expansion (aromatic bonds must live inside rings) and for aromaticity.
-
-## Step 2 – Kekulé Expansion (`kekulize::perceive`)
-
-Input molecules may use `BondOrder::Aromatic` to indicate resonance. Downstream components only understand concrete single/double orders, so this pass searches each connected aromatic system for a valid Kekulé assignment:
-
-1. Group aromatic bonds into systems via BFS.
-2. Run a backtracking solver that tries all single/double assignments while enforcing per-element valence limits (e.g., neutral nitrogen allows at most one double bond inside the system).
-3. Apply the chosen orders to both the bond list and adjacency lists.
-
-If any aromatic bond connects atoms that were not marked as ring members in Step 1, the pass emits `TyperError::PerceptionFailed` with details about the failing step.
-
-## Step 3 – Electron & Charge Heuristics (`electrons::perceive`)
-
-With concrete bond orders in place the perceiver can reason about electrons. Rather than a single generic formula, this crate implements a template-style pass that covers the tricky functional groups DREIDING cares about.
-
-- **Nitro / nitrone / carboxylate:** assigns the correct +1/−1 charge split between the heteroatoms and sets heteroatom lone pairs (e.g., nitro oxygen holds three lone pairs when singly bound).
-- **Sulfur & halogen oxyanions:** handles `SO2`, sulfones, sulfonates, and perchlorate-style centers by distributing charges onto terminal oxygens and leaving the central atom positively charged when appropriate.
-- **Ammonium/iminium/onium/phosphonium:** detects degree-four nitrogen, oxygen, sulfur, and phosphorus centers and enforces +1 charges with the right lone-pair count.
-- **Phenolate/enolate anions:** forces single-bound oxygens attached to `sp2` carbons to carry −1 charge and extra lone pairs.
-
-Atoms touched here are marked as “processed” so they are not recomputed later in the same pass. All other atoms fall back to generic electron counting using valence, bond order, and formal charge.
+Each pass mutates the shared `AnnotatedMolecule`. Later stages can rely on the invariants produced by earlier ones (e.g., hybridization assumes resonance has already run). The following sections summarize the responsibilities of each pass.
 
-## Step 4 – Aromaticity (`aromaticity::perceive`)
+## 1. Ring Detection — `rings::perceive`
 
-Armed with ring membership, explicit bond orders, and lone-pair counts, the aromaticity pass evaluates each ring system:
+- **Goal:** Identify the Smallest Set of Smallest Rings (SSSR) so that downstream logic knows which atoms are cyclic and how large the ring is.
+- **How it works:** The pass enumerates candidates by temporarily removing bonds and searching for alternative paths, then selects a minimal cycle basis via bit-vector Gaussian elimination. Each ring is stored as a sorted list of atom IDs. Matching atoms are flagged with `is_in_ring = true` and `smallest_ring_size`.
+- **Why it matters:** Aromaticity, resonance, and hybridization all depend on knowing whether atoms participate in cyclic systems.
 
-1. Build ring adjacency to cluster fused rings into systems.
-2. For each system, ensure every atom is potentially planar (steric number ≤ 3, or special lone-pair cases).
-3. Count π-electrons per atom:
-   - Endocyclic double bond → +1
-   - Lone pair donated into the ring (no exocyclic π bond) → +2
-   - Formal charge −1 → +2; formal charge +1 → +0
-   - Resonant flag from previous steps → +1 (captures delocalized contributions)
-4. Classify as aromatic if the total satisfies $4n+2$, anti-aromatic if $4n$, neither otherwise.
+## 2. Kekulé Expansion — `kekulize::perceive`
 
-If an entire fused system fails the aromatic test, each constituent ring is re-evaluated individually. At the end, every atom records whether it is aromatic, anti-aromatic, or neither.
+- **Goal:** Replace every aromatic bond with an explicit single/double assignment that respects valence and heteroatom allowances.
+- **How it works:** The pass validates that every aromatic bond is fully contained within a ring, partitions the aromatic bonds into connected systems, and runs a backtracking Kekulé solver for each system. Nitrogen and phosphorus receive one "double-bond allowance" to enforce the correct valence counts. Successful assignments update both the bond table and the adjacency lists.
+- **Why it matters:** Electron counting, aromaticity, and resonance all rely on concrete bond multiplicities. Without Kekulé expansion, delocalized input would prevent later passes from recognizing π-bonds.
 
-## Step 5 – Resonance & Conjugation (`resonance::perceive`)
+## 3. Electron Assignments — `electrons::perceive`
 
-This phase bridges the gap between localized double bonds and the broader “is this atom part of a conjugated system?” question.
+- **Goal:** Populate `formal_charge` and `lone_pairs` for every atom via a mixture of targeted functional-group heuristics and a general valence fallback.
+- **How it works:**
+  - Pattern recognizers detect nitrones, nitro groups, sulfoxides/sulfones, halogen oxyanions, phosphoryl fragments, carboxylates, ammonium/iminium, onium/phosphonium ions, and enolate/phenate anions. When a pattern matches, the participating atoms are marked as processed and assigned the chemically expected charges/lone pairs.
+  - Atoms that remain unprocessed fall back to a valence-based routine that balances valence electrons, bond orders, and existing formal charges.
+- **Why it matters:** Accurate charges and lone-pair counts underpin aromaticity checks, resonance detection, and hybridization inference.
 
-1. Call `pauling::find_resonance_systems` to obtain conjugated components and mark `is_in_conjugated_system` for all returned atoms.
-2. Augment the raw result with chemistry-specific heuristics:
-   - Aromatic atoms are always conjugated.
-   - Amides, thioamides, and sulfonamides propagate conjugation from the carbonyl carbon into neighboring lone-pair donors.
-   - Halogen oxyanions clamp their terminal oxygens to **not** conjugate (prevents incorrectly labeling perchlorate oxygens as resonant).
-   - Purely σ-bound sulfurs are demoted out of conjugation even if upstream heuristics temporarily marked them.
+## 4. Aromaticity — `aromaticity::perceive`
 
-This pass also sets `is_resonant` for atoms that originated from aromatic bonds before Kekulé expansion so that the typing engine can recognize `*_R` atom types without conflating resonance with aromaticity.
+- **Goal:** Classify fused ring systems as aromatic, anti-aromatic, or neither using a Hückel π-electron count with planarity heuristics.
+- **How it works:** Rings are grouped into systems that share atoms. For each system, the model counts π-electrons contributed by in-ring double bonds, lone pairs, or formal charges, while also checking for cross-conjugation and planarity (via steric number heuristics). If the system is aromatic (4n+2 electrons) every atom in the system receives `is_aromatic = true`. Anti-aromatic systems (4n electrons) instead set `is_anti_aromatic = true`. Mixed systems fall back to per-ring evaluation.
+- **Why it matters:** Aromatic flags influence resonance, hybridization, and ultimately the typing rules (e.g., `C_R`, `N_R`).
 
-## Step 6 – Hybridization (`hybridization::perceive`)
+## 5. Resonance — `resonance::perceive`
 
-The final pass converts the accumulated data into a definitive `Hybridization` enum per atom. The logic proceeds in priority order:
+- **Goal:** Mark atoms that participate in conjugated systems, even when they are not part of a strictly aromatic ring.
+- **How it works:** The pass delegates to the external `pauling` crate to discover resonance systems, then overlays project-specific heuristics:
+  - Aromatic atoms are always marked conjugated.
+  - Amide/thioamide and sulfonamide motifs promote their heteroatom donors into conjugation when lone pairs are available.
+  - Hypervalent halogen oxyanions have their terminal oxygens demoted to avoid false conjugation.
+  - Purely σ-bound sulfurs that slipped through the previous steps are also demoted.
+- **Why it matters:** Conjugation flags feed hybridization inference and help the typing engine distinguish resonant atoms from plain sp² centers.
 
-1. **Non-hybridized elements:** alkali/alkaline metals, halogens, noble gases, and most transition metals default to `Hybridization::None`.
-2. **Conjugated overrides:** atoms flagged as conjugated (and not anti-aromatic) with steric number ≤ 3—or steric 4 with a lone pair—downgrade to `Hybridization::Resonant`, collapsing their steric number to 3 so the builder emits impropers.
-3. **Aromatic planarity:** aromatic atoms default to `SP2` even if their steric number would imply 4, enforcing planarity in ring systems.
-4. **VSEPR fallback:** remaining atoms map steric numbers to `SP3`/`SP2`/`SP`/`None`. Steric numbers above 4 trigger `PerceptionError::HybridizationInference`, surfacing impossible inputs early.
+## 6. Hybridization — `hybridization::perceive`
 
-Each atom's final steric number is normalized after hybridization so that later components can rely on `steric_number` without recalculating.
+- **Goal:** Assign the final `Hybridization` enum and normalized `steric_number` for every atom.
+- **How it works:** For each atom:
+  - Elements that never hybridize (alkali metals, halogens, most transition metals) are stamped as `Hybridization::None`.
+  - Conjugated atoms that are not anti-aromatic collapse to `Hybridization::Resonant`, even when their raw steric number is four (lone-pair donation collapses the geometry to trigonal).
+  - Aromatic atoms default to `Hybridization::SP2`.
+  - Remaining atoms fall back to VSEPR rules derived from `degree + lone_pairs`.
+  - The stored `steric_number` is renormalized so downstream consumers can rely on 2/3/4 despite resonance collapsing a formal 4 to 3.
+- **Why it matters:** The typing rules operate primarily on the `hybridization`, aromatic flags, and neighbor information produced by this pass. The builder also copies the final hybridization into the emitted topology.
 
-## Output Guarantees
+---
 
-After the six passes finish, `AnnotatedMolecule` contains:
+By the end of chemical perception every `AnnotatedAtom` contains:
 
-- Fully expanded bond orders (no `BondOrder::Aromatic`).
-- Ring membership and smallest ring sizes.
-- Formal charges, lone-pair counts, and degree for every atom.
-- Aromatic / anti-aromatic / conjugated / resonant flags.
-- Final steric number and `Hybridization` assignment.
+- identity (`element`, `id`, `degree`)
+- ring context (`is_in_ring`, `smallest_ring_size`)
+- electronic structure (`formal_charge`, `lone_pairs`, `is_resonant`, `is_in_conjugated_system`)
+- aromaticity flags (`is_aromatic`, `is_anti_aromatic`)
+- geometry (`hybridization`, normalized `steric_number`)
 
-This rich, immutable snapshot is the sole source of chemical truth for the Typing Engine and the Topology Builder.
+This richly annotated molecule is the single source of truth for both the typing engine and the topology builder.