Skip to main content

coeus_nn/init/
error.rs

1use std::error::Error;
2
3/// Failure returned by neural-network random initialization.
4#[derive(Debug, thiserror::Error)]
5#[non_exhaustive]
6pub enum InitializationError<E>
7where
8    E: Error + 'static,
9{
10    /// The tensor rank is outside the shared provider dispatch domain.
11    #[error("random initialization requires rank {minimum}..={maximum}, got {actual}")]
12    InvalidRank {
13        /// Observed tensor rank.
14        actual: usize,
15        /// Smallest supported rank.
16        minimum: usize,
17        /// Largest supported rank.
18        maximum: usize,
19    },
20    /// A distribution parameter is not finite in the requested scalar type.
21    #[error("initialization parameter {parameter} must be finite, got {value}")]
22    NonFiniteParameter {
23        /// Rejected parameter name.
24        parameter: &'static str,
25        /// Original public input value.
26        value: f64,
27    },
28    /// Uniform bounds are reversed.
29    #[error("uniform lower bound must not exceed upper bound, got {low} > {high}")]
30    InvalidUniformBounds {
31        /// Requested lower bound.
32        low: f64,
33        /// Requested upper bound.
34        high: f64,
35    },
36    /// A normal standard deviation is negative.
37    #[error("normal standard deviation must be non-negative, got {value}")]
38    NegativeStandardDeviation {
39        /// Rejected standard deviation.
40        value: f64,
41    },
42    /// A fan parameter is zero.
43    #[error("{parameter} must be positive, got {value}")]
44    InvalidFan {
45        /// Rejected fan parameter.
46        parameter: &'static str,
47        /// Rejected value.
48        value: usize,
49    },
50    /// Attention width cannot be partitioned across the configured heads.
51    #[error("attention d_model {d_model} must be positive and divisible by {heads} heads")]
52    InvalidHeadConfiguration {
53        /// Model width.
54        d_model: usize,
55        /// Compile-time head count.
56        heads: usize,
57    },
58    /// A transformer stack requested no layers.
59    #[error("transformer layer count must be positive, got {layers}")]
60    InvalidLayerCount {
61        /// Compile-time layer count.
62        layers: usize,
63    },
64    /// Xavier fan arithmetic overflowed `usize`.
65    #[error("fan_in + fan_out exceeds usize: {fan_in} + {fan_out}")]
66    FanArithmeticOverflow {
67        /// Input fan.
68        fan_in: usize,
69        /// Output fan.
70        fan_out: usize,
71    },
72    /// A derived fan product overflowed `usize`.
73    #[error("{lhs_name} * {rhs_name} exceeds usize: {lhs} * {rhs}")]
74    FanProductOverflow {
75        /// Left factor name.
76        lhs_name: &'static str,
77        /// Left factor value.
78        lhs: usize,
79        /// Right factor name.
80        rhs_name: &'static str,
81        /// Right factor value.
82        rhs: usize,
83    },
84    /// The selected backend provider rejected initialization.
85    #[error("{operation} backend initialization failed")]
86    Backend {
87        /// Initialization family being dispatched.
88        operation: &'static str,
89        /// Backend-owned typed failure.
90        #[source]
91        source: E,
92    },
93}
94
95impl<E> From<E> for InitializationError<E>
96where
97    E: Error + 'static,
98{
99    fn from(source: E) -> Self {
100        Self::Backend {
101            operation: "parameter construction",
102            source,
103        }
104    }
105}