Description:

Implements a transformative refactoring of the core optimization engine to achieve an order-of-magnitude performance increase. This overhaul replaces the current model of full-system re-evaluation with a hyper-efficient Incremental Energy Manager that utilizes a zero-clone, "try-revert" transaction model.

The primary goal is to eliminate the two main performance bottlenecks identified in complex system simulations: massive system call overhead (sys time) from frequent memory allocations (system.clone()) and redundant O(n) calculations for unchanged parts of the system. This will be achieved by maintaining a live energy state and calculating only the energy delta of conformational changes, enabling rapid exploration of the conformational space.

Tasks:

• Phase 1: Architect the Incremental Energy Manager (engine/energy.rs)

  • Create a new module engine/energy.rs and a public struct IncrementalEnergyManager.
  • Implement the new() constructor for the manager. This includes a one-time, O(n²) pre-computation to build an interaction_cache that stores the sum of interaction energies for each active sidechain with all other active sidechains.
  • Unit Test: Write a comprehensive unit test for IncrementalEnergyManager::new() that verifies both the initial current_score and the per-residue interaction_cache values against a manually calculated "golden" dataset.

• Phase 2: Implement the Zero-Clone "Try-Revert" Mechanism

  • In engine/placement.rs:
    • Introduce a new RAII-based struct PlacementTransaction.
    • Implement an apply() method on PlacementTransaction that performs an in-place rotamer placement on the manager's working_state. It must record the original rotamer index before modification.
    • Implement the Drop trait for PlacementTransaction to automatically revert any applied changes, ensuring the system state is restored when the transaction goes out of scope.
  • In engine/energy.rs:
    • Implement IncrementalEnergyManager::start_transaction() to create and return a PlacementTransaction.
    • Refactor IncrementalEnergyManager::calculate_delta_for_swap to be &mut self. Inside, use a PlacementTransaction to temporarily apply the new rotamer, calculate the energy delta against the now-modified system, and let the transaction automatically revert the change. This must completely eliminate system.clone() from this critical path.

• Phase 3: Implement Efficient State & Cache Updates

  • In engine/energy.rs:
    • Implement IncrementalEnergyManager::apply_swap. This method will:
      • Update the current_score with the pre-calculated delta in O(1).
      • Permanently apply the new rotamer to working_state.system.
      • Perform an efficient O(n) update of the interaction_cache, recalculating interaction terms only for the atom pairs involving the changed residue.
  • Integration Test: Write a crucial test for calculate_delta_for_swap and apply_swap. It must verify that after applying a swap, the manager's new current_score is numerically identical to a full, non-incremental rescoring of the new working_state.system.

• Phase 4: Integrate into Workflows (workflows/place.rs)

  • In engine/state.rs: Add a new method OptimizationState::submit_solution(score, state) to allow submitting solutions from the energy manager.
  • In workflows/place.rs:
    • Refactor final_refinement:
      • Initialize IncrementalEnergyManager once before the main loop.
      • Replace all full system rescoring with calls to energy_manager.calculate_delta_for_swap to find the best move.
      • Use energy_manager.apply_swap to accept a move.
      • Use state.submit_solution() to update the candidate solutions.
    • Refactor resolve_clashes:
      • Initialize IncrementalEnergyManager at the start.
      • After doublet_optimization::run returns the best rotamer pair, use the manager's calculate_delta... and apply_swap methods sequentially to apply the two-residue change and update the energy state.
      • Use state.submit_solution() to record the new state.