syren 0.6.0

A parallel Rust framework for agent-based models with ECS storage, scheduling, messaging, environments, and optional GPU execution.
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
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

//! Error types for the `environment` module.
//!
//! ## Design
//!
//! The `environment` module uses its own error enum. All public environment
//! APIs return `Result<T, EnvironmentError>`.
//!
//! At scheduler / system boundaries the
//! [`From<EnvironmentError> for ECSError`] implementation (defined in
//! `src/engine/error/mod.rs` behind `#[cfg(feature = "environment")]`)
//! converts the error into `ECSError::Environment`, preserving full
//! diagnostic context.

/// Errors that can arise when reading or writing the simulation environment.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum EnvironmentError {
    /// A key was requested that was never registered.
    KeyNotFound(String),

    /// The registered type for a key does not match the type requested by the
    /// caller.
    TypeMismatch {
        /// The key whose type mismatched.
        key: String,
        /// The name of the type that was registered.
        expected: &'static str,
        /// The name of the type that was requested.
        actual: &'static str,
    },

    /// An environment lock was poisoned by a panic while held.
    LockPoisoned {
        /// Description of the poisoned lock.
        what: &'static str,
    },

    /// An environment key was declared with an empty name.
    EmptyKey,

    /// A GPU uniform buffer's packed byte size did not match the expected WGSL layout.
    UniformLayoutMismatch {
        /// Expected packed byte size.
        expected: usize,
        /// Actual packed byte size.
        actual: usize,
    },
}

impl std::fmt::Display for EnvironmentError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            EnvironmentError::KeyNotFound(k) => write!(f, "key not found: {k}"),
            EnvironmentError::TypeMismatch {
                key,
                expected,
                actual,
            } => write!(
                f,
                "type mismatch for key '{key}': expected {expected}, got {actual}"
            ),
            EnvironmentError::LockPoisoned { what } => {
                write!(f, "environment lock poisoned: {what}")
            }
            EnvironmentError::EmptyKey => f.write_str("environment key must not be empty"),
            EnvironmentError::UniformLayoutMismatch { expected, actual } => write!(
                f,
                "uniform layout mismatch: packed {actual} bytes but expected {expected}"
            ),
        }
    }
}

impl std::error::Error for EnvironmentError {}

/// Convenience alias for environment-domain results.
pub type EnvironmentResult<T> = Result<T, EnvironmentError>;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::engine::error::ECSError;

    #[test]
    fn display_key_not_found() {
        let e = EnvironmentError::KeyNotFound("interest_rate".into());
        assert!(e.to_string().contains("interest_rate"));
    }

    #[test]
    fn display_type_mismatch() {
        let e = EnvironmentError::TypeMismatch {
            key: "tax_rate".into(),
            expected: "f32",
            actual: "f64",
        };
        let s = e.to_string();
        assert!(s.contains("tax_rate"));
        assert!(s.contains("f32"));
        assert!(s.contains("f64"));
    }

    #[test]
    fn into_ecs_error_preserves_variant() {
        let e = EnvironmentError::KeyNotFound("x".into());
        let ecs: ECSError = e.into();
        assert!(matches!(
            ecs,
            ECSError::Environment(EnvironmentError::KeyNotFound(_))
        ));
    }

    #[test]
    fn into_ecs_error_preserves_type_mismatch() {
        let e = EnvironmentError::TypeMismatch {
            key: "rate".into(),
            expected: "f32",
            actual: "f64",
        };
        let ecs: ECSError = e.into();
        assert!(matches!(
            ecs,
            ECSError::Environment(EnvironmentError::TypeMismatch { .. })
        ));
        // Verify the Display output retains the original message.
        assert!(ecs.to_string().contains("rate"));
        assert!(ecs.to_string().contains("f32"));
    }

    #[test]
    fn display_uniform_layout_mismatch() {
        let e = EnvironmentError::UniformLayoutMismatch {
            expected: 16,
            actual: 8,
        };
        let s = e.to_string();
        assert!(s.contains("16"));
        assert!(s.contains("8"));
    }
}