cheq/
error.rs

1//! Error types for the `cheq` library.
2//!
3//! This module provides a comprehensive `CheqError` enum that covers various failure modes,
4//! including parameter lookup failures, SCF convergence issues, linear algebra errors,
5//! I/O problems, and deserialization errors. This centralized error handling ensures
6//! consistent and actionable error reporting across all operations in the library.
7
8use std::path::PathBuf;
9use thiserror::Error;
10
11/// The primary error type for all fallible operations in the `cheq` library.
12///
13/// This enum is designed to be comprehensive, providing clear and actionable
14/// information for each potential failure mode, from I/O issues to numerical
15/// convergence problems. It implements `std::error::Error`, allowing it to be
16/// composed with other error types in application code.
17#[derive(Error, Debug)]
18pub enum CheqError {
19    /// Indicates that the parameters for a specific element, identified by its
20    /// atomic number, could not be found in the provided `Parameters` set.
21    ///
22    /// This is a common error when attempting to calculate charges for a molecule
23    /// containing an element not defined in the parameter file.
24    #[error("Atomic parameters not found for element with atomic number: {0}")]
25    ParameterNotFound(u8),
26
27    /// Occurs when the Self-Consistent Field (SCF) iterative process fails to
28    /// converge to the desired tolerance within the maximum number of allowed iterations.
29    ///
30    /// This can happen with unusual molecular geometries or problematic parameter sets.
31    /// The final charge difference (`delta`) is provided for diagnostic purposes.
32    #[error(
33        "SCF failed to converge after {max_iterations} iterations. Final charge difference: {delta:.2e}"
34    )]
35    NotConverged {
36        /// The maximum number of iterations that were performed.
37        max_iterations: u32,
38        /// The largest absolute change in any atomic charge during the final iteration.
39        delta: f64,
40    },
41
42    /// A failure within the underlying linear algebra solver, for example,
43    /// if the matrix system is singular or ill-conditioned.
44    #[error("Failed to solve the linear matrix system: {0}")]
45    LinalgError(String),
46
47    /// An I/O error that occurred while attempting to read a parameter file.
48    ///
49    /// The path to the file and the underlying I/O error are provided for context.
50    #[error("I/O error at path '{path}': {source}")]
51    IoError {
52        /// The path of the file that caused the I/O error.
53        path: PathBuf,
54        /// The underlying `std::io::Error`.
55        #[source]
56        source: std::io::Error,
57    },
58
59    /// An error that occurred while parsing a parameter file, typically indicating
60    /// invalid TOML or a structural mismatch with the expected `Parameters` format.
61    #[error("Failed to deserialize TOML parameters: {0}")]
62    DeserializationError(#[from] toml::de::Error),
63
64    /// A validation error indicating that the input slice of atoms was empty.
65    /// At least one atom is required to perform a calculation.
66    #[error("Input validation failed: at least one atom is required for a calculation")]
67    NoAtoms,
68}
cheq/error.rs

cheq/
error.rs
