oxicuda_rl/
error.rs

1//! Error types for `oxicuda-rl`.
2
3use thiserror::Error;
4
5/// All errors produced by the OxiCUDA RL library.
6#[derive(Debug, Error)]
7pub enum RlError {
8    /// Underlying CUDA driver error.
9    #[error("CUDA driver error: {0}")]
10    Cuda(#[from] oxicuda_driver::CudaError),
11
12    /// Replay buffer has zero capacity.
13    #[error("replay buffer capacity must be > 0")]
14    ZeroCapacity,
15
16    /// Replay buffer does not yet contain enough transitions to sample.
17    #[error("not enough transitions in buffer: have {have}, need {need}")]
18    InsufficientTransitions {
19        /// Number of transitions currently stored.
20        have: usize,
21        /// Number requested.
22        need: usize,
23    },
24
25    /// Dimension mismatch between observation, action, or reward tensors.
26    #[error("dimension mismatch: expected {expected}, got {got}")]
27    DimensionMismatch {
28        /// Expected number of elements.
29        expected: usize,
30        /// Actual number of elements.
31        got: usize,
32    },
33
34    /// Invalid hyperparameter value.
35    #[error("invalid hyperparameter `{name}`: {msg}")]
36    InvalidHyperparameter {
37        /// Parameter name.
38        name: String,
39        /// Description of why it is invalid.
40        msg: String,
41    },
42
43    /// Policy returned a probability vector that does not sum to 1 within
44    /// tolerance.
45    #[error("invalid probability distribution: sum={sum:.6}, expected 1.0 ± {tol}")]
46    InvalidDistribution {
47        /// Actual sum of the probability vector.
48        sum: f32,
49        /// Tolerance used for the check.
50        tol: f32,
51    },
52
53    /// Attempt to sample from an empty categorical distribution.
54    #[error("cannot sample from empty categorical distribution")]
55    EmptyDistribution,
56
57    /// N-step buffer flush requested before enough steps were collected.
58    #[error("n-step buffer incomplete: have {have} steps, need {need}")]
59    NStepIncomplete {
60        /// Steps currently accumulated.
61        have: usize,
62        /// Steps required (= n).
63        need: usize,
64    },
65
66    /// Priority sum in segment tree dropped to zero (all priorities are zero).
67    #[error("priority segment tree sum is zero — all priorities must be > 0")]
68    ZeroPrioritySum,
69
70    /// Feature not yet implemented.
71    #[error("not supported: {0}")]
72    NotSupported(String),
73
74    /// Internal logic error — should never surface in correct code.
75    #[error("internal error: {0}")]
76    Internal(String),
77}
78
79/// Convenience alias.
80pub type RlResult<T> = Result<T, RlError>;
oxicuda_rl/error.rs

oxicuda_rl/
error.rs
