cheq/
types.rs

1//! This module defines the core types used in the cheq library for representing atoms and calculation results.
2//!
3//! It includes the `AtomView` trait for abstracting atom data access, the `Atom` struct for concrete atom
4//! representation, and the `CalculationResult` struct for storing the outcomes of charge equilibration
5//! calculations. These types form the foundation for the decoupled design that allows integration with
6//! various molecular data structures.
7
8/// A trait for viewing atom data without owning it.
9///
10/// This trait provides a common interface for accessing an atom's atomic number and 3D position,
11/// enabling the charge equilibration solver to work with different atom representations. By decoupling
12/// the solver from specific data structures, users can integrate the `cheq` library with their own
13/// molecular representations without data conversion overhead.
14pub trait AtomView {
15    /// Returns the atomic number of the atom.
16    ///
17    /// The atomic number uniquely identifies the chemical element and is used to look up atomic
18    /// parameters such as electronegativity and hardness.
19    fn atomic_number(&self) -> u8;
20
21    /// Returns the 3D position of the atom in Cartesian coordinates.
22    ///
23    /// The position is represented as an array of three `f64` values corresponding to x, y, and z
24    /// coordinates. This information is crucial for calculating interatomic distances and Coulomb
25    /// interactions in the charge equilibration method.
26    fn position(&self) -> [f64; 3];
27}
28
29/// A concrete representation of an atom with atomic number and position.
30///
31/// This struct provides a simple, owned implementation of the `AtomView` trait. It can be used
32/// directly for basic atom representations or as a building block for more complex atom types that
33/// include additional properties like velocities or forces.
34#[derive(Debug, Clone, Copy, PartialEq)]
35pub struct Atom {
36    /// The atomic number of the atom, identifying its chemical element.
37    pub atomic_number: u8,
38    /// The 3D position of the atom in Cartesian coordinates.
39    pub position: [f64; 3],
40}
41
42impl AtomView for Atom {
43    #[inline(always)]
44    fn atomic_number(&self) -> u8 {
45        self.atomic_number
46    }
47
48    #[inline(always)]
49    fn position(&self) -> [f64; 3] {
50        self.position
51    }
52}
53
54/// The result of a charge equilibration calculation.
55///
56/// This struct encapsulates the output of a successful charge equilibration run, including the
57/// computed partial atomic charges, the equilibrated chemical potential, and diagnostic information
58/// about the iterative solution process.
59#[derive(Debug, Clone, PartialEq)]
60pub struct CalculationResult {
61    /// The computed partial atomic charges for each atom in the system.
62    ///
63    /// Charges are stored in the same order as the input atoms. The sum of all charges equals the
64    /// total system charge specified in the calculation.
65    pub charges: Vec<f64>,
66    /// The equilibrated chemical potential achieved at convergence.
67    ///
68    /// This value represents the uniform chemical potential across all atoms when the system has
69    /// reached charge equilibration.
70    pub equilibrated_potential: f64,
71    /// The number of iterations performed to reach convergence.
72    ///
73    /// This provides insight into the computational effort required and can help diagnose
74    /// convergence issues in difficult systems.
75    pub iterations: u32,
76}
cheq/types.rs

cheq/
types.rs
