Description:

The current data model, based on Vec<T> and usize indices, is highly optimized for initial construction via the MolecularSystemBuilder but is fundamentally brittle and unsafe for the dynamic modifications required by side-chain packing algorithms. Operations such as deleting a residue or mutating a side-chain cause cascading index invalidations across the entire MolecularSystem, leading to data inconsistency and making safe implementation of core algorithms nearly impossible. Redundant data fields (chain_id, res_id in Atom) further complicate state management.

Tasks:

• Introduce Arena Dependency:

  • Add the slotmap crate to scream-core's dependencies. It provides a well-tested and high-performance SlotMap collection suitable for this purpose.

• Redefine Core Data Structures:

  • Atom: Remove index, res_id, and chain_id. Add a parent: ResidueKey field to link it to its parent residue.
  • Residue: Replace atom_indices: Vec<usize> with atoms: Vec<AtomKey>. Add a parent: ChainKey field. The atom_name_map will now map String to AtomKey.
  • Chain: Replace residues: Vec<Residue> with residues: Vec<ResidueKey>. The residue_map will now map the residue sequence number to ResidueKey.

• Redesign MolecularSystem:

  • Replace atoms: Vec<Atom>, chains: Vec<Chain> with atoms: SlotMap<AtomKey, Atom>, residues: SlotMap<ResidueKey, Residue>, and chains: SlotMap<ChainKey, Chain>.
  • Implement a comprehensive and safe public API for all structural queries and modifications (e.g., add_atom_to_residue, remove_residue, get_atom_mut).
  • Update mapping tables (atom_serial_map, chain_id_map) to store arena keys instead of usize indices.

• Update MolecularSystemBuilder:

  • Refactor the builder to work with the new arena-based MolecularSystem. start_chain, start_residue, and add_atom will now insert into the arenas and manage the stable keys.

• Adapt Downstream Code:

  • Modify the bgf.rs I/O implementation to use the new builder and correctly traverse the redesigned MolecularSystem for writing.
  • Update all public-facing methods that previously returned &[Atom] or &[Chain] to provide iterators over the arena collections.

• Rewrite Unit Tests:

  • Thoroughly update and expand unit tests for system.rs, chain.rs, residue.rs, and builder.rs to validate the new data model's correctness, especially for modification and deletion scenarios.
  • Add tests to ensure that attempting to use a key after its corresponding entity has been deleted results in a predictable and safe failure (e.g., None or panic).