Summary:

Introduces a major refactoring of the chemical perception engine to decouple aromaticity detection from the more general concept of resonance. The previous implementation incorrectly conflated the two, leading to mistyping of non-aromatic but resonant systems (e.g., amides, carboxylates). The new, more sophisticated pipeline now consists of six ordered stages, including explicit Kekulé expansion, charge/lone-pair perception via an expert template system, and a dedicated resonance detection pass. This results in significantly more accurate hybridization and DREIDING atom type assignments, particularly for _R types, across a broader range of chemical structures.

Changes:

• Implemented a Six-Stage Perception Pipeline:

  • Re-architected the processor module into a formal, six-stage pipeline: Rings -> Kekulize -> Electrons -> Aromaticity -> Resonance -> Hybridization.
  • Each stage is now a distinct, well-defined pass that enriches an AnnotatedMolecule data structure, ensuring a deterministic and chemically correct flow of information.
  • Introduced the pauling crate for robust resonance system detection.

• Decoupled Aromaticity from Resonance:

  • Aromaticity perception is now a dedicated pass that only flags atoms in rings satisfying Hückel's rule.
  • A new, separate resonance perception pass identifies all atoms in any conjugated π-system, whether cyclic or linear.
  • The Hybridization enum now has a distinct Resonant variant, which is used as the primary condition for assigning _R types.

• Enhanced Charge and Lone Pair Perception:

  • Removed the formal_charge from the public MolecularGraph::add_atom API.
  • Implemented a new electrons perception pass that automatically infers formal charges and lone pairs.
  • The pass uses an expert system of functional group templates to correctly handle complex cases like nitro groups, sulfoxides, carboxylates, and zwitterionic amino acids.

• Refined DREIDING Rule Set:

  • The default ruleset (default.rules.toml) has been overhauled to leverage the new, more precise perception data.
  • Rules for _R types (e.g., C_R, N_R, O_R) are now correctly keyed on hybridization = "Resonant" instead of the overly restrictive is_aromatic = true.
  • This corrects the typing for numerous functional groups (amides, carboxylates, guanidinium, etc.) that are resonant but not aromatic.

• Expanded and Refined Integration Test Suite:

  • Removed explicit charge parameters from all test case definitions to validate the new charge perception logic.
  • Corrected the expected types for dozens of atoms in the test suite to match the more accurate _R assignments produced by the new engine.
  • Added new, complex test cases for nucleic acids and challenging structures from the original DREIDING paper to validate the enhanced perception capabilities.

• Improved CI and Project Documentation:

  • Strengthened the CI pipeline with additional checks for formatting, linting, and documentation.
  • Updated all architectural and user-facing documentation to reflect the new perception pipeline and simplified API.