Description:

This foundational task establishes the core data contract for the entire cheq library. It involves initializing the project structure and defining all primary public-facing data structures and error types. The design will ensure a robust, type-safe, and user-friendly public API. Key components include a flexible AtomView trait to decouple the library from specific user data formats, a comprehensive CheqError enum for robust error handling, and clear CalculationResult and Parameters structs for unambiguous input/output. This milestone is critical for enabling all subsequent development of the parameter handling, mathematical core, and the main solver.

Tasks:

• Phase 1: Project Initialization and Structure

  • Initialize a new Rust library project named cheq.
  • Add crate metadata to Cargo.toml, including the one-line description, keywords, authors, and licensing (MIT).
  • Create the full directory structure as defined in the project architecture document (src/params, src/math, src/solver, etc.).
  • Create an initial README.md and license files.

• Phase 2: Define Core Public Types

  • In src/types.rs:
    • Define the AtomView trait with atomic_number() and position() methods. Document its purpose of enabling zero-cost abstraction for user data.
    • Define the concrete Atom struct as a convenience implementation of AtomView.
    • Define the CalculationResult struct containing charges, equilibrated_potential, and iterations. Ensure all fields are clearly documented with their units.
  • In src/params/mod.rs:
    • Define the ElementData struct for elemental properties (chi, j, radius, n).
    • Define the Parameters struct which will hold a HashMap<u8, ElementData>.
  • Implement Debug, Clone, and PartialEq traits where appropriate for these structs.

• Phase 3: Architect Custom Error Handling

  • In src/error.rs:
    • Add thiserror as a dependency.
    • Define the main CheqError enum.
    • Implement initial error variants relevant to this and the next phase, such as ParameterNotFound(u8), NoAtoms, IoError, and DeserializationError.
    • Ensure CheqError derives thiserror::Error and Debug.

• Phase 4: Establish the Public API Facade

  • In src/lib.rs:
    • Set up the module declarations (mod error;, mod types;, etc.).
    • Add the crate-level documentation header, including a placeholder for a future usage example.
    • Re-export all public-facing types (CheqError, AtomView, Atom, CalculationResult, Parameters, ElementData) for a clean, flat API surface.