Description:

This task implements the heart of the library: the forge module. This module orchestrates the transformation of a raw chemical or biological System into a fully parameterized ForgedSystem ready for molecular dynamics simulation. It acts as the central coordinator, integrating topology perception (via dreid-typer) and partial charge calculation (via cheq) with a custom parameterization engine that strictly applies the rules of the DREIDING force field. The design emphasizes modularity, configuration-driven behavior, and complete encapsulation of the underlying physics engines. The module will process the internal System representation, assign atom types, calculate charges, and then generate all bond, angle, torsion, and non-bonded potential terms required for the final output.

Tasks:

• Phase 1: Module Structure and Configuration

  • Create the full directory structure: src/forge/, src/forge/error.rs, src/forge/config.rs, src/forge/state.rs, src/forge/adapters.rs, src/forge/params.rs, and src/forge/engine.rs.
  • In src/forge/error.rs: Define a specialized Error enum for the parameterization process, covering rule parsing errors, missing topology, and failures from cheq or dreid-typer.
  • In src/forge/config.rs:
    • Define ForgeConfig as the main control struct.
    • Define ChargeMethod enum (QEq vs. None) and QEqConfig struct.
    • Add fields for optional custom rules (TOML string) and custom parameters (TOML string).

• Phase 2: Internal State and Adapters

  • In src/forge/state.rs:
    • Define ProcessingState struct. It should hold the original System and parallel vectors for mutable properties: charges, atom_types (String), and hybridizations.
    • Implement cheq::AtomView for ProcessingState to allow zero-copy charge calculation.
  • In src/forge/adapters.rs:
    • Implement perceive_topology: Converts System to dreid-typer::MolecularGraph, runs the typer (using custom rules if provided), and writes types/hybridization back to ProcessingState.
    • Implement calculate_charges: Configures and runs the cheq solver based on ChargeMethod, updating ProcessingState.charges.

• Phase 3: Parameter Database

  • In src/forge/params.rs:
    • Define data structures (DreidingParams, AtomParamRaw) that mirror Tables I-VII from the DREIDING paper.
    • Implement a TOML parser using serde.
    • Embed the default DREIDING parameters using include_str! and provide a load_parameters function that merges defaults with user overrides.

• Phase 4: The Parameterization Engine

  • In src/forge/engine.rs:
    • Implement the core parameterize function.
    • Bond Generation: Iterate topology bonds, lookup $R_0$ and $k$, apply Eq 4a/6/7.
    • Angle Generation: Iterate topology angles, lookup $\theta_0$, apply Eq 10a.
    • Torsion Generation: Implement the complex hybridization-matching logic (Eq 13) to assign barriers ($V$), periodicity ($n$), and phase.
    • Inversion Generation: Detect planar centers and assign umbrella potentials (Eq 28).
    • Non-Bonded Generation:
      • Generate the unique list of atom_types.
      • Create VdwPairPotential entries for all type pairs.
      • Identify H-Bond donors/acceptors based on atom types and generate HBondPotential entries (using the "Charge" convention parameters: $D_{hb}=7.0$).
    • Assemble and return the final ForgedSystem.

• Phase 5: Public API and Integration

  • In src/forge/mod.rs:
    • Implement the public process(System, &ForgeConfig) -> Result<ForgedSystem> function that sequences the entire pipeline.
    • Re-export necessary types (ForgeConfig, ChargeMethod) to the library root.
  • Verification:
    • Write unit tests for the parameter loader.
    • Write an integration test that runs the full forge pipeline on a simple molecule (e.g., ethane) and asserts that correct types ("C_3") and bond parameters are assigned.