Description:

Implements a foundational refactoring of the energy calculation framework to introduce a scientifically rigorous, absolute energy model. The goal is to replace the current relative "optimization score" with a true TotalSystemEnergy that is comparable across different optimization scopes and always improves upon the input structure.

This will be achieved by decomposing the total energy into a dynamic OptimizationScore (used internally for speed) and a static, pre-calculated EnergyOffsetConstant. All user-facing energies will be reported as the absolute TotalSystemEnergy.

Tasks:

• Phase 1: Data Structure Enhancement (core/models)

  • Introduce a public AtomRole enum (Backbone, Sidechain, Ligand, etc.) in atom.rs.
  • Add a pub role: AtomRole field to the Atom struct.
  • (Optional but Recommended) Add sidechain_atoms_cache: Vec<AtomId> and backbone_atoms_cache: Vec<AtomId> to the Residue struct for efficient access.
  • Implement new high-level query methods in MolecularSystem for fetching atoms by role (e.g., get_sidechain_atoms_of_residue, get_fixed_protein_atoms).
  • Cleanup: Remove the exact_match_atoms and connection_points fields from PlacementInfo and update relevant .toml files.

• Phase 2: Logic & Algorithm Refactoring (core/forcefield & engine/tasks)

  • In parameterization.rs:
    • Modify Parameterizer::parameterize_system to be the sole authority for setting the Atom.role for every atom in the system, using PlacementInfo and ChainType as guides.
  • In el_energy.rs:
    • Refactor compute_energies_for_unit to ensure the query_atoms set only contains the atoms of the active sidechain (Sc_A).
    • Ensure environment_atoms correctly includes all other atoms in the system (all backbones, all fixed residues, background, etc.).
  • In total_energy.rs:
    • Rename the file to optimization_score.rs.
    • Rewrite the run function to calculate OptimizationScore = Σ E_EL + E_inter(Sc_A, Sc_A). The interaction term must be calculated between active sidechains only.

• Phase 3: State & Workflow Integration

  • In engine/state.rs:
    • Refactor OptimizationState:
      • Add an energy_offset: EnergyTerm field.
      • Rename current_energy to current_score.
      • Rework submit_current_solution to calculate total_energy = self.current_score + self.energy_offset before comparing and storing solutions.
  • In workflows/place.rs:
    • Implement the new "Setup & Pre-computation" logic at the beginning of the run function.
    • Define and partition all atomic sets (Sc_A, Bb_A, Sc_F, Bb_F, B).
    • (New Task Call) Create and call a new task engine/tasks/offset_energy.rs to calculate the EnergyOffsetConstant (E(FixedAtoms, FixedAtoms)).
    • Calculate the initial TotalSystemEnergy of the input structure.
    • Pass the calculated EnergyOffsetConstant to OptimizationState::new.
    • Store the initial input structure and its energy as the first candidate solution.
  • Logging & Reporting: Ensure all user-facing output (logs, final report) displays the TotalSystemEnergy.