Skip to main content

differential_equations/
operator_problem.rs

1/// A vector problem driven by a dense, possibly state- and time-dependent
2/// linear operator: `u' = A(u, p, t) u`.
3///
4/// The operator callback overwrites a row-major `dimension × dimension`
5/// buffer. This mirrors SciML's updateable `MatrixOperator` contract while
6/// making dimensions explicit in Rust.
7pub struct LinearOperatorProblem<O, P> {
8    pub(crate) operator: O,
9    pub(crate) initial_state: Vec<f64>,
10    pub(crate) time_span: (f64, f64),
11    pub(crate) parameters: P,
12}
13
14impl<O, P> LinearOperatorProblem<O, P> {
15    /// Constructs a checked linear-operator problem.
16    pub fn new(
17        operator: O,
18        initial_state: impl Into<Vec<f64>>,
19        time_span: (f64, f64),
20        parameters: P,
21    ) -> Result<Self, ConfigurationError> {
22        let initial_state = initial_state.into();
23        if initial_state.is_empty() {
24            return Err(ConfigurationError::EmptyData {
25                context: "linear operator state",
26            });
27        }
28        Ok(Self {
29            operator,
30            initial_state,
31            time_span,
32            parameters,
33        })
34    }
35
36    /// Returns the initial state.
37    pub fn initial_state(&self) -> &[f64] {
38        &self.initial_state
39    }
40
41    /// Returns the integration time span.
42    pub fn time_span(&self) -> (f64, f64) {
43        self.time_span
44    }
45
46    /// Returns the user parameters.
47    pub fn parameters(&self) -> &P {
48        &self.parameters
49    }
50
51    /// Returns the state dimension.
52    pub fn dimension(&self) -> usize {
53        self.initial_state.len()
54    }
55
56    /// Evaluates the row-major operator matrix at `state` and `time`.
57    ///
58    /// The output must contain `dimension * dimension` entries and `state`
59    /// must match the problem dimension. Non-finite operator entries are
60    /// rejected with [`SolveError::NonFiniteDerivative`].
61    pub fn evaluate_operator(
62        &self,
63        output: &mut [f64],
64        state: &[f64],
65        time: f64,
66    ) -> Result<(), SolveError>
67    where
68        O: Fn(&mut [f64], &[f64], &P, f64),
69    {
70        let dimension = self.dimension();
71        if state.len() != dimension || output.len() != dimension * dimension {
72            return Err(SolveError::EvaluationDimensionMismatch);
73        }
74        (self.operator)(output, state, &self.parameters, time);
75        finite_operator(output)
76    }
77}
78
79#[derive(Clone, Copy, Debug, Eq, PartialEq)]
80pub(crate) enum LieRepresentation {
81    Vector,
82    Matrix,
83}
84
85/// A homogeneous-space or matrix Lie-group problem driven by a dense Lie
86/// algebra generator.
87///
88/// Use [`vector`](Self::vector) for actions `u <- exp(Ω)u`, and
89/// [`matrix`](Self::matrix) for conjugation actions on a square matrix state.
90pub struct LieGroupProblem<O, P> {
91    pub(crate) operator: O,
92    pub(crate) initial_state: Vec<f64>,
93    pub(crate) time_span: (f64, f64),
94    pub(crate) parameters: P,
95    pub(crate) group_dimension: usize,
96    pub(crate) representation: LieRepresentation,
97}
98
99impl<O, P> LieGroupProblem<O, P> {
100    /// Constructs a problem whose state is a vector acted on by the group.
101    pub fn vector(
102        operator: O,
103        initial_state: impl Into<Vec<f64>>,
104        time_span: (f64, f64),
105        parameters: P,
106    ) -> Result<Self, ConfigurationError> {
107        let initial_state = initial_state.into();
108        if initial_state.is_empty() {
109            return Err(ConfigurationError::EmptyData {
110                context: "Lie-group vector state",
111            });
112        }
113        let group_dimension = initial_state.len();
114        Ok(Self {
115            operator,
116            initial_state,
117            time_span,
118            parameters,
119            group_dimension,
120            representation: LieRepresentation::Vector,
121        })
122    }
123
124    /// Constructs a problem whose state is a square group matrix.
125    pub fn matrix(
126        operator: O,
127        initial_matrix: impl Into<Vec<f64>>,
128        dimension: usize,
129        time_span: (f64, f64),
130        parameters: P,
131    ) -> Result<Self, ConfigurationError> {
132        let initial_state = initial_matrix.into();
133        let expected =
134            dimension
135                .checked_mul(dimension)
136                .ok_or(ConfigurationError::DimensionOverflow {
137                    context: "Lie-group matrix",
138                })?;
139        if dimension == 0 || initial_state.len() != expected {
140            return Err(ConfigurationError::DimensionMismatch {
141                context: "Lie-group matrix state",
142            });
143        }
144        Ok(Self {
145            operator,
146            initial_state,
147            time_span,
148            parameters,
149            group_dimension: dimension,
150            representation: LieRepresentation::Matrix,
151        })
152    }
153
154    /// Returns the flattened initial state.
155    pub fn initial_state(&self) -> &[f64] {
156        &self.initial_state
157    }
158
159    /// Returns the integration time span.
160    pub fn time_span(&self) -> (f64, f64) {
161        self.time_span
162    }
163
164    /// Returns the user parameters.
165    pub fn parameters(&self) -> &P {
166        &self.parameters
167    }
168
169    /// Returns the underlying group dimension.
170    pub fn group_dimension(&self) -> usize {
171        self.group_dimension
172    }
173
174    /// Reports whether the state uses the square-matrix representation.
175    pub fn is_matrix_state(&self) -> bool {
176        self.representation == LieRepresentation::Matrix
177    }
178
179    /// Evaluates the Lie-algebra generator at `state` and `time`.
180    ///
181    /// The generator output must be a flattened `group_dimension` square
182    /// matrix and `state` must match the selected vector or matrix
183    /// representation. Non-finite entries are rejected.
184    pub fn evaluate_operator(
185        &self,
186        output: &mut [f64],
187        state: &[f64],
188        time: f64,
189    ) -> Result<(), SolveError>
190    where
191        O: Fn(&mut [f64], &[f64], &P, f64),
192    {
193        if state.len() != self.initial_state.len()
194            || output.len() != self.group_dimension * self.group_dimension
195        {
196            return Err(SolveError::EvaluationDimensionMismatch);
197        }
198        (self.operator)(output, state, &self.parameters, time);
199        finite_operator(output)
200    }
201}
202use crate::{ConfigurationError, SolveError};
203
204fn finite_operator(values: &[f64]) -> Result<(), SolveError> {
205    values
206        .iter()
207        .all(|value| value.is_finite())
208        .then_some(())
209        .ok_or(SolveError::NonFiniteDerivative)
210}