Description:

Focuses on building the foundational utils module for the scream-core crate. This module will encapsulate all low-level, stateless utility functions, providing a clean, modern, and high-performance toolkit for the rest of the application. The goal is to extract and centralize all geometry, linear algebra, and string parsing logic from the original C++ codebase, replacing it with robust implementations based on the nalgebra crate and idiomatic Rust. This will decouple high-level algorithms from low-level mathematical details, improve testability, and provide a solid, well-documented foundation for all subsequent development.

Tasks:

• Establish Module Structure (utils/mod.rs):

  • Create the top-level utils module.
  • Define and export two primary sub-modules: geometry and parsing.

• Implement Geometry Toolkit (utils/geometry.rs):

  • Integrate the nalgebra crate for all vector, point, and matrix operations.
  • Implement core geometric calculations, including dihedral_angle.
  • Implement rotational transformation functions, such as rotation_around_axis and align_vectors_rotation, to replace the C++ matrix logic.
  • Implement specialized coordinate generation functions, like create_beta_carbon_position and hydrogen placement utilities (generate_sp3_hydrogens, etc.).
  • Add functions for structural comparison, such as calculate_rmsd.

• Implement Parsing and Type Utilities (utils/parsing.rs):

  • Implement a suite of type-checking functions (e.g., is_backbone_atom_name, is_standard_amino_acid) using efficient data structures like phf::Set.
  • Create a robust aa_code_converter for seamless conversion between one-letter and three-letter amino acid codes.
  • Implement parse_mutation_info to safely parse "MutInfo" style strings (e.g., "A123_C") into structured data.

• Write Comprehensive Unit Tests:

  • Write unit tests for all major geometric functions, verifying calculations against known values.
  • Add tests for all string parsing and type-checking utilities to ensure they correctly handle valid, invalid, and edge-case inputs.