Description:

This task will establish the core data contract for the entire library by creating a new core module. This module will define all primary data structures using Rust's enum and struct system to ensure type safety and clarity. The design will feature a clear separation between the input MolecularGraph (representing raw connectivity) and the output MolecularTopology (representing the final, typed force field topology). This foundational work is critical for enabling all subsequent stages of analysis, typing, and building.

Tasks:

• Phase 1: Define Core Chemical Enums

  • Create a new module core/mod.rs.
  • Define the Element enum, covering all relevant elements from the DREIDING paper (H, C, N, O, Si, P, S, etc.).
  • Define the BondOrder enum (Single, Double, Triple, Aromatic).
  • Define the Hybridization enum (SP3, SP2, SP1, Resonant, Unknown).
  • Implement Debug, Clone, PartialEq, Eq, and Hash traits for all enums where appropriate.

• Phase 2: Architect the Input and Output Graph Structures

  • Create a new module core/graph.rs.
  • Input Structure: Define the AtomNode and BondEdge structs, culminating in the MolecularGraph struct. Ensure all fields are clearly documented, especially the requirement for unique IDs.
  • Output Structure: Define the Atom, Bond, Angle, ProperDihedral, and ImproperDihedral structs.
  • Canonicalization: Document and implement canonical ordering for Bond's atom_ids (e.g., smaller ID first) to ensure uniqueness.
  • Convention: Document the atom ordering convention for Angle (center middle) and ImproperDihedral (center at a defined position, e.g., third).
  • Define the final MolecularTopology struct that aggregates all output components.

• Phase 3: Implement Custom Error Types

  • Create a new module core/error.rs.
  • Define the main TyperError enum.
  • Implement initial error variants relevant to this phase, such as InvalidInputGraph { reason: String }.
  • Implement the std::error::Error and fmt::Display traits for TyperError to ensure user-friendly messages and good library citizenship.

• Phase 4: Establish the Public API Facade

  • In src/lib.rs:
    • Create the basic module structure (mod core;, mod engine;, etc.).
    • Re-export all public-facing data structures from core::graph and core::error.
    • Define the skeleton of the main public function pub fn type_molecule(graph: &MolecularGraph) -> Result<MolecularTopology, TyperError>. The initial implementation can simply return an unimplemented! error or a placeholder.
  • Unit Test: Add a simple test in src/lib.rs to verify that the public data structures can be instantiated, ensuring they are correctly exposed.