Skip to main content

mathverse_calculus/
ode.rs

1//! Ordinary differential equation solvers.
2//!
3//! Provides numerical methods for solving first-order ODEs of the form dy/dt = f(t, y).
4
5use mathverse_core::error::MathResult;
6
7/// Forward Euler method for solving dy/dt = f(t, y).
8///
9/// Returns a vector of (t, y) pairs.
10///
11    /// ```
12    /// use mathverse_calculus::ode::euler;
13    /// // dy/dt = y, y(0) = 1, solution: y = e^t
14    /// let result = euler(&|t, y| y, 0.0, 1.0, 1.0, 100).unwrap();
15    /// let y_final = result.last().unwrap().1;
16    /// assert!((y_final - 1.0_f64.exp()).abs() < 0.02);
17    /// ```
18    pub fn euler(f: &dyn Fn(f64, f64) -> f64, t0: f64, y0: f64, t_end: f64, steps: usize) -> MathResult<Vec<(f64, f64)>> {
19    if steps == 0 {
20        return Err(mathverse_core::error::MathError::InvalidArgument("euler: steps must be > 0"));
21    }
22    let dt = (t_end - t0) / steps as f64;
23    let mut result = Vec::with_capacity(steps + 1);
24    let mut t = t0;
25    let mut y = y0;
26    result.push((t, y));
27    for _ in 0..steps {
28        y += dt * f(t, y);
29        t += dt;
30        result.push((t, y));
31    }
32    Ok(result)
33}
34
35/// Fourth-order Runge-Kutta method (RK4) for solving dy/dt = f(t, y).
36///
37/// Returns a vector of (t, y) pairs. Much more accurate than Euler.
38///
39    /// ```
40    /// use mathverse_calculus::ode::runge_kutta_4;
41    /// // dy/dt = y, y(0) = 1, solution: y = e^t
42    /// let result = runge_kutta_4(&|t, y| y, 0.0, 1.0, 1.0, 10).unwrap();
43    /// let y_final = result.last().unwrap().1;
44    /// assert!((y_final - 1.0_f64.exp()).abs() < 1e-5);
45    /// ```
46    pub fn runge_kutta_4(f: &dyn Fn(f64, f64) -> f64, t0: f64, y0: f64, t_end: f64, steps: usize) -> MathResult<Vec<(f64, f64)>> {
47    if steps == 0 {
48        return Err(mathverse_core::error::MathError::InvalidArgument("runge_kutta_4: steps must be > 0"));
49    }
50    let dt = (t_end - t0) / steps as f64;
51    let mut result = Vec::with_capacity(steps + 1);
52    let mut t = t0;
53    let mut y = y0;
54    result.push((t, y));
55    for _ in 0..steps {
56        let k1 = dt * f(t, y);
57        let k2 = dt * f(t + dt / 2.0, y + k1 / 2.0);
58        let k3 = dt * f(t + dt / 2.0, y + k2 / 2.0);
59        let k4 = dt * f(t + dt, y + k3);
60        y += (k1 + 2.0 * k2 + 2.0 * k3 + k4) / 6.0;
61        t += dt;
62        result.push((t, y));
63    }
64    Ok(result)
65}
66
67/// Midpoint method (second-order Runge-Kutta) for solving dy/dt = f(t, y).
68///
69/// Returns a `Result` of (t, y) pairs.
70///
71/// ```
72/// use mathverse_calculus::ode::midpoint;
73/// // dy/dt = y, y(0) = 1, solution: y = e^t
74/// let result = midpoint(&|t, y| y, 0.0, 1.0, 1.0, 100).unwrap();
75/// let y_final = result.last().unwrap().1;
76/// assert!((y_final - 1.0_f64.exp()).abs() < 0.001);
77/// ```
78pub fn midpoint(f: &dyn Fn(f64, f64) -> f64, t0: f64, y0: f64, t_end: f64, steps: usize) -> MathResult<Vec<(f64, f64)>> {
79    if steps == 0 {
80        return Err(mathverse_core::error::MathError::InvalidArgument("midpoint: steps must be > 0"));
81    }
82    let dt = (t_end - t0) / steps as f64;
83    let mut result = Vec::with_capacity(steps + 1);
84    let mut t = t0;
85    let mut y = y0;
86    result.push((t, y));
87    for _ in 0..steps {
88        let k = dt * f(t + dt / 2.0, y + dt * f(t, y) / 2.0);
89        y += k;
90        t += dt;
91        result.push((t, y));
92    }
93    Ok(result)
94}
95
96/// System of ODEs solver using RK4.
97///
98/// Solves dy/dt = f(t, y) where y is a vector.
99///
100    /// ```
101    /// use mathverse_calculus::ode::runge_kutta_4_system;
102    /// // Harmonic oscillator: d²x/dt² = -x
103    /// // Convert to system: dx/dt = v, dv/dt = -x
104    /// let f = |t: f64, y: &[f64]| -> Vec<f64> {
105    ///     vec![y[1], -y[0]]
106    /// };
107    /// let result = runge_kutta_4_system(&f, 0.0, &[1.0, 0.0], 2.0 * core::f64::consts::PI, 100).unwrap();
108    /// let y_final = &result.last().unwrap().1;
109    /// assert!((y_final[0] - 1.0).abs() < 1e-6); // Should return to initial position
110    /// ```
111pub fn runge_kutta_4_system(
112    f: &dyn Fn(f64, &[f64]) -> Vec<f64>,
113    t0: f64,
114    y0: &[f64],
115    t_end: f64,
116    steps: usize,
117) -> MathResult<Vec<(f64, Vec<f64>)>> {
118    if steps == 0 {
119        return Err(mathverse_core::error::MathError::InvalidArgument("runge_kutta_4_system: steps must be > 0"));
120    }
121    let dt = (t_end - t0) / steps as f64;
122    let n = y0.len();
123    let mut result = Vec::with_capacity(steps + 1);
124    let mut t = t0;
125    let mut y = y0.to_vec();
126    result.push((t, y.clone()));
127    for _ in 0..steps {
128        let k1 = f(t, &y).iter().map(|&v| dt * v).collect::<Vec<_>>();
129        let y1: Vec<f64> = y.iter().zip(k1.iter()).map(|(&yi, &k1i)| yi + k1i / 2.0).collect();
130        let k2 = f(t + dt / 2.0, &y1).iter().map(|&v| dt * v).collect::<Vec<_>>();
131        let y2: Vec<f64> = y.iter().zip(k2.iter()).map(|(&yi, &k2i)| yi + k2i / 2.0).collect();
132        let k3 = f(t + dt / 2.0, &y2).iter().map(|&v| dt * v).collect::<Vec<_>>();
133        let y3: Vec<f64> = y.iter().zip(k3.iter()).map(|(&yi, &k3i)| yi + k3i).collect();
134        let k4 = f(t + dt, &y3).iter().map(|&v| dt * v).collect::<Vec<_>>();
135        for i in 0..n {
136            y[i] += (k1[i] + 2.0 * k2[i] + 2.0 * k3[i] + k4[i]) / 6.0;
137        }
138        t += dt;
139        result.push((t, y.clone()));
140    }
141    Ok(result)
142}
143
144/// ODE solver methods for the [`OdeProblem`] builder.
145#[derive(Debug, Clone, Copy, PartialEq, Eq)]
146pub enum OdeMethod {
147    /// Forward Euler (1st order, fixed step)
148    Euler,
149    /// Midpoint / RK2 (2nd order, fixed step)
150    Midpoint,
151    /// Classical RK4 (4th order, fixed step)
152    Rk4,
153}
154
155/// Builder for ODE problems — scipy-like API.
156///
157/// ```
158/// use mathverse_calculus::ode::{OdeProblem, OdeMethod};
159/// // dy/dt = y, y(0) = 1, solve to t=1
160/// let sol = OdeProblem::new(&|_, y| y, (0.0, 1.0), 1.0)
161///     .method(OdeMethod::Rk4)
162///     .steps(100)
163///     .solve()
164///     .unwrap();
165/// let y_final = sol.last().unwrap().1;
166/// assert!((y_final - 1.0_f64.exp()).abs() < 1e-6);
167/// ```
168#[derive(Clone)]
169pub struct OdeProblem<'a> {
170    f: &'a dyn Fn(f64, f64) -> f64,
171    t_span: (f64, f64),
172    y0: f64,
173    method: OdeMethod,
174    steps: usize,
175}
176
177impl<'a> OdeProblem<'a> {
178    /// Create a new ODE problem.
179    pub fn new(f: &'a dyn Fn(f64, f64) -> f64, t_span: (f64, f64), y0: f64) -> Self {
180        Self {
181            f,
182            t_span,
183            y0,
184            method: OdeMethod::Rk4,
185            steps: 1000,
186        }
187    }
188
189    /// Set the solver method.
190    #[must_use]
191    pub fn method(mut self, m: OdeMethod) -> Self {
192        self.method = m;
193        self
194    }
195
196    /// Set the number of steps.
197    #[must_use]
198    pub fn steps(mut self, n: usize) -> Self {
199        self.steps = n;
200        self
201    }
202
203    /// Solve the ODE.
204    pub fn solve(self) -> MathResult<Vec<(f64, f64)>> {
205        match self.method {
206            OdeMethod::Euler => euler(self.f, self.t_span.0, self.y0, self.t_span.1, self.steps),
207            OdeMethod::Midpoint => midpoint(self.f, self.t_span.0, self.y0, self.t_span.1, self.steps),
208            OdeMethod::Rk4 => runge_kutta_4(self.f, self.t_span.0, self.y0, self.t_span.1, self.steps),
209        }
210    }
211}
212
213#[cfg(test)]
214mod tests {
215    use super::*;
216    use core::f64::consts::PI;
217
218    #[test]
219    fn euler_test() {
220        // dy/dt = y, y(0) = 1, solution: y = e^t
221        let result = euler(&|t, y| y, 0.0, 1.0, 1.0, 100).unwrap();
222        let y_final = result.last().unwrap().1;
223        assert!((y_final - 1.0_f64.exp()).abs() < 0.02);
224    }
225
226    #[test]
227    fn runge_kutta_4_test() {
228        // dy/dt = y, y(0) = 1, solution: y = e^t
229        let result = runge_kutta_4(&|t, y| y, 0.0, 1.0, 1.0, 10).unwrap();
230        let y_final = result.last().unwrap().1;
231        assert!((y_final - 1.0_f64.exp()).abs() < 1e-5);
232    }
233
234    #[test]
235    fn midpoint_test() {
236        // dy/dt = y, y(0) = 1, solution: y = e^t
237        let result = midpoint(&|t, y| y, 0.0, 1.0, 1.0, 100).unwrap();
238        let y_final = result.last().unwrap().1;
239        assert!((y_final - 1.0_f64.exp()).abs() < 0.001);
240    }
241
242    #[test]
243    fn runge_kutta_4_system_test() {
244        // Harmonic oscillator: d²x/dt² = -x
245        let f = |_t: f64, y: &[f64]| -> Vec<f64> { vec![y[1], -y[0]] };
246        let result = runge_kutta_4_system(&f, 0.0, &[1.0, 0.0], 2.0 * PI, 100).unwrap();
247        let y_final = &result.last().unwrap().1;
248        assert!((y_final[0] - 1.0).abs() < 1e-6);
249        assert!((y_final[1] - 0.0).abs() < 1e-6);
250    }
251
252    #[test]
253    fn harmonic_oscillator_energy() {
254        // Energy should be conserved: E = 0.5 * (x² + v²)
255        let f = |_t: f64, y: &[f64]| -> Vec<f64> { vec![y[1], -y[0]] };
256        let result = runge_kutta_4_system(&f, 0.0, &[1.0, 0.0], 10.0 * PI, 10000).unwrap();
257        let y_final = &result.last().unwrap().1;
258        let energy = 0.5 * (y_final[0] * y_final[0] + y_final[1] * y_final[1]);
259        assert!((energy - 0.5).abs() < 1e-4, "energy drifted: {energy}");
260    }
261
262    #[test]
263    fn steps_zero_returns_err() {
264        assert!(euler(&|_, y| y, 0.0, 1.0, 1.0, 0).is_err());
265        assert!(midpoint(&|_, y| y, 0.0, 1.0, 1.0, 0).is_err());
266        assert!(runge_kutta_4(&|_, y| y, 0.0, 1.0, 1.0, 0).is_err());
267        assert!(runge_kutta_4_system(&|_, y: &[f64]| y.to_vec(), 0.0, &[1.0], 1.0, 0).is_err());
268    }
269
270    #[test]
271    fn ode_problem_builder() {
272        // dy/dt = y, y(0) = 1, solution: y = e^t
273        let sol = OdeProblem::new(&|_, y| y, (0.0, 1.0), 1.0)
274            .method(OdeMethod::Rk4)
275            .steps(100)
276            .solve()
277            .unwrap();
278        let y_final = sol.last().unwrap().1;
279        assert!((y_final - 1.0_f64.exp()).abs() < 1e-6);
280
281        // Test Euler method
282        let sol_euler = OdeProblem::new(&|_, y| y, (0.0, 1.0), 1.0)
283            .method(OdeMethod::Euler)
284            .steps(1000)
285            .solve()
286            .unwrap();
287        let y_euler = sol_euler.last().unwrap().1;
288        assert!((y_euler - 1.0_f64.exp()).abs() < 0.02);
289    }
290
291    #[test]
292    fn decay_test() {
293        // dy/dt = -y, y(0) = 1, solution: y = e^(-t)
294        let result = runge_kutta_4(&|_t, y| -y, 0.0, 1.0, 1.0, 10).unwrap();
295        let y_final = result.last().unwrap().1;
296        assert!((y_final - (-1.0_f64).exp()).abs() < 1e-6);
297    }
298}