Description:

Focuses on building the entire forcefield module for the scream-core crate. This module is the computational heart of SCREAM, responsible for translating physicochemical principles into a quantitative scoring function. The primary goal is to create a modular, data-driven, and high-performance system that separates force field parameters, pure potential energy functions, and the high-level scoring logic. This will replace the tightly-coupled and hard-coded energy calculation logic from the original C++ codebase. The final module will be capable of loading all necessary parameters from configuration files and calculating all required energy terms, including the "flat-bottom" potential, for any given molecular system.

Tasks:

• Parameterization (forcefield/params.rs)

  • Design Parameter File Format: Convert the parameter data hard-coded in C++ and scattered across .par/.rtf files into a set of structured TOML files (e.g., vdw.toml, hbond.toml, charges.toml, delta.toml, topology.toml).
  • Define Parameter Structs: Create a comprehensive set of Rust structs (ForceFieldParams, VdwParam, ResidueTopology, etc.) that mirror the structure of the new TOML files.
  • Implement Parameter Loader: Using the serde and toml crates, implement a robust loader (ForceFieldParams::load(...)) that can parse all parameter files into the ForceFieldParams struct.
  • Write Unit Tests for Loading: Create tests to ensure all parameter types (VDW, HBond, charges, delta, topology) are loaded correctly from sample TOML files.

• Pure Potential Functions (forcefield/potentials.rs)

  • Implement VDW Potentials: Create pure functions like lj_12_6 and flat_bottom_lj_12_6 that take numerical inputs (distance, radius, depth, delta) and return an energy value.
  • Implement Coulomb Potential: Create a coulomb function that calculates electrostatic energy based on charges, distance, and a dielectric constant.
  • Implement HBond Potential: Implement the DREIDING 12-10 hydrogen bond potential, dreiding_hbond, which takes distance and angle as inputs. Implement its flat-bottom variant as well.
  • Write Comprehensive Math-Level Unit Tests: For each potential function, write unit tests that verify its correctness against known values at various distances and a ngles, especially at edge cases (e.g., at the equilibrium distance, within the flat-bottom region).

• Scoring Engine (forcefield/engine.rs)

  • Define ScoringEngine Struct: Create the ScoringEngine struct, which will hold an instance of the loaded ForceFieldParams.
  • Implement System Pre-processing: Create a method ScoringEngine::prepare_system(&self, system: &mut MolecularSystem) that:
    • Assigns correct force_field_type and partial_charge to each atom based on topology and charge scheme.
    • Caches frequently needed parameters (like vdw_radius, hbond_type_id, delta) onto each Atom struct to accelerate subsequent calculations.
  • Implement empty_lattice_energy Method: This core method will calculate the interaction energy of a target residue's sidechain with the fixed molecular environment. It must correctly:
    • Identify target and environment atoms based on AtomFlags.
    • Handle 1-2, 1-3, and 1-4 intramolecular exclusions.
    • Call the appropriate pure functions from the potentials module.
    • Return a structured result (EnergyTerms { vdw, coulomb, ... }).
  • Implement interaction_energy Method: Similar to the above, but calculates the energy between two specified (and variable) residues.