You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-Aromaticity and resonance flags (`is_aromatic`, `is_anti_aromatic`, `is_resonant`).
40
40
- An adjacency list for efficient neighbor traversal.
41
41
-**Design Rationale:**
42
42
-**Centralized Knowledge:** By pre-calculating and storing all relevant properties in one place, the subsequent typing and building phases can be implemented as efficient, stateless queries against this data structure. This avoids redundant calculations.
Copy file name to clipboardExpand all lines: docs/02_perception.md
+5-8Lines changed: 5 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -57,20 +57,17 @@ Each pass mutates the shared `AnnotatedMolecule`. Later stages can rely on the i
57
57
## 5. Resonance — `resonance::perceive`
58
58
59
59
-**Goal:** Mark atoms that participate in conjugated systems, even when they are not part of a strictly aromatic ring.
60
-
-**How it works:** The pass delegates to the external `pauling` crate to discover resonance systems, then overlays project-specific heuristics:
61
-
- Aromatic atoms are always marked conjugated.
62
-
- Amide/thioamide and sulfonamide motifs promote their heteroatom donors into conjugation when lone pairs are available.
63
-
- Hypervalent halogen oxyanions have their terminal oxygens demoted to avoid false conjugation.
64
-
- Purely σ-bound sulfurs that slipped through the previous steps are also demoted.
65
-
-**Why it matters:** Conjugation flags feed hybridization inference and help the typing engine distinguish resonant atoms from plain sp² centers.
60
+
-**How it works:** The pass uses strict substructure matching to detect chemically significant resonance motifs. It operates in two phases:
61
+
1.**Core functional group detection:** Pattern recognizers identify carboxylates, nitro groups, guanidinium ions, thiourea/thioamide fragments, amides, and phosphate groups. When a motif is found, all participating atoms are flagged as resonant, and the system (atoms + bonds) is recorded for later topology emission.
62
+
2.**Peripheral propagation:** Heteroatoms (O, N, S) with lone pairs that are adjacent to already-resonant atoms are themselves promoted to resonant.
63
+
-**Why it matters:** Conjugation flags feed hybridization inference and help the typing engine distinguish resonant atoms from plain sp² centers. The recorded resonance systems inform the builder phase which bonds should receive the resonant bond order.
66
64
67
65
## 6. Hybridization — `hybridization::perceive`
68
66
69
67
-**Goal:** Assign the final `Hybridization` enum and normalized `steric_number` for every atom.
70
68
-**How it works:** For each atom:
71
69
- Elements that never hybridize (alkali metals, halogens, most transition metals) are stamped as `Hybridization::None`.
72
70
- 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).
73
-
- Aromatic atoms default to `Hybridization::SP2`.
74
71
- Remaining atoms fall back to VSEPR rules derived from `degree + lone_pairs`.
75
72
- The stored `steric_number` is renormalized so downstream consumers can rely on 2/3/4 despite resonance collapsing a formal 4 to 3.
76
73
-**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.
@@ -81,7 +78,7 @@ By the end of chemical perception every `AnnotatedAtom` contains:
81
78
82
79
- identity (`element`, `id`, `degree`)
83
80
- ring context (`is_in_ring`, `smallest_ring_size`)
conditions = { element = "N", hybridization = "SP2" }
22
22
```
23
23
24
24
At runtime, `typing::rules::parse_rules` converts the TOML into strongly typed `Rule` structures. `typing::rules::get_default_rules` lazily parses the embedded `resources/default.rules.toml`, so applications can either use the canonical ruleset directly or append their own entries before starting the typing engine.
@@ -36,13 +36,11 @@ The following table details every valid key that can be used inside the `conditi
36
36
|`formal_charge`| Integer | The formal charge of the atom (e.g., `1`, `0`, `-1`). |
37
37
|`degree`| Integer | The number of directly bonded neighbor atoms. |
38
38
|`lone_pairs`| Integer | The number of lone electron pairs, as calculated during the Perception Phase. |
39
-
|`steric_number`| Integer | The sum of `degree` and `lone_pairs`. A primary indicator of geometry. |
|`is_in_ring`| Boolean |`true` if the atom is part of any detected ring system. |
42
41
|`is_aromatic`| Boolean |`true` if the atom is part of a perceived aromatic system. |
43
42
|`is_anti_aromatic`| Boolean |`true` if perception tagged the atom as belonging to an anti-aromatic ring. |
44
43
|`is_resonant`| Boolean |`true` if resonance analysis marked the atom as delocalized (e.g., phenoxide oxygen). |
45
-
|`smallest_ring_size`| Integer | The size of the smallest ring the atom belongs to (e.g., `5` for furan). |
46
44
|**Neighbor-Based Properties**|| Properties derived from the atom's immediate neighbors. |
47
45
|`neighbor_elements`| Table | Specifies the **exact counts** of neighboring elements. Atoms not listed are assumed to be zero. |
48
46
|`neighbor_types`| Table | Specifies the **exact counts** of the **final assigned types** of neighboring atoms. This is the key condition that enables context-dependent, iterative typing. |
0 commit comments