scatrs 0.3.0

Fast, linearized, rigorously validated single-scattering calculations for spherical and spheroidal particles (Lorenz–Mie, layered spheres, T-matrix spheroids, size distributions)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

//! Error type shared by every scatrs computation.
//!
//! Every fallible function returns [`Result`], whose [`Error`] says what went wrong:
//!
//! * [`Error::InvalidInput`]: an argument is outside its valid range or a documented limit
//!   (for example a negative imaginary part of the refractive index). Nothing is computed.
//! * [`Error::OutsideValidatedDomain`]: the inputs are valid, but outside the domain where the
//!   accuracy has been validated. Set `allow_unvalidated` to compute anyway.
//! * [`Error::NotConverged`]: an iteration missed the accuracy it promises.
//!
//! An ensemble whose size integration does not meet its tolerance is not an error: its result
//! is returned, with `converged` false.

/// Errors returned by scatrs computations.
#[derive(Debug, Clone, PartialEq, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// An input is outside its mathematically valid range (for example `|x| > 1` for `x = cos θ`).
    #[error("invalid input: {0}")]
    InvalidInput(String),
    /// An iterative or truncated computation did not reach the requested accuracy.
    #[error("not converged: achieved {achieved:e}, requested {requested:e}")]
    NotConverged {
        /// Accuracy actually reached (method-specific measure).
        achieved: f64,
        /// Accuracy that was requested.
        requested: f64,
    },
    /// The inputs are valid but outside the domain where accuracy has been validated.
    #[error("outside validated domain: {0}")]
    OutsideValidatedDomain(String),
}

/// Result alias using [`Error`].
pub type Result<T> = core::result::Result<T, Error>;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn messages_are_informative() {
        assert_eq!(
            Error::InvalidInput("n must be >= 1".into()).to_string(),
            "invalid input: n must be >= 1"
        );
        assert_eq!(
            Error::NotConverged {
                achieved: 1e-3,
                requested: 1e-6
            }
            .to_string(),
            "not converged: achieved 1e-3, requested 1e-6"
        );
        assert_eq!(
            Error::OutsideValidatedDomain("x > 2e4".into()).to_string(),
            "outside validated domain: x > 2e4"
        );
    }
}