differential-equations 0.5.3

//! Defines the trait for systems of Delay Differential Equations (DDEs) used by numerical solvers.

use crate::traits::{Real, State};

/// Trait for defining a system of Delay Differential Equations (DDEs).
///
/// The system is generally represented as:
/// `dy/dt = f(t, y(t), y(t - tau1), y(t - tau2), ...)`
/// where `y` is the state vector, `t` is time, and `y(t - tau_i)` represents
/// the state at some past time (a delay).
///
pub trait DDE<const L: usize, T = f64, Y = f64>
where
    T: Real,
    Y: State<T>,
{
    /// Computes the time derivative `dy/dt` of the system state.
    ///
    /// This function defines the right-hand side `f` of the DDE system:
    /// `dy/dt = f(t, y(t), yd(t - tau1), yd(t - tau2), ...)`.
    ///
    /// # Arguments
    ///
    /// * `t`: The current time `t` at which the derivative is being evaluated.
    /// * `y`: A reference to the current state vector `y(t)`.
    /// * `yd`: An array of past state vectors a resulting `td` points generated by the `lags` function.
    /// * `dydt`: A mutable reference to the state vector where the computed derivative `dy/dt` should be stored.
    ///
    /// # Panics
    /// The history function call can panic if the request time is greater than or equal to the current time `t`.
    ///
    fn diff(&self, t: T, y: &Y, yd: &[Y; L], dydt: &mut Y);

    /// Computes the desired lagging values, tau, for the system.
    ///
    /// This function takes the lags and uses the given initial history function,
    /// interpolation between calculated states, and extrapolation to find the
    /// delayed values, `yd = y(t - tau)`. This function can be used to calculate constant,
    /// time-varying, or state-dependent lags.
    ///
    /// # Example
    /// * For a constant lag `tau` simply set `lags[0] = tau`.
    /// * For a time-varying lag, e.g., `lags[0] = t * 0.1`.
    /// * For a state-dependent lag, e.g., `lags[0] = y[0] * 0.1`.
    ///
    /// Note how the delay point `td` is not passed to this function. The solver will
    /// calculate the delay point `td` based on the current time `t` and the lags provided.
    ///
    /// # Arguments
    /// * `t`: The current time `t` at which the lags are being evaluated.
    /// * `y`: A reference to the current state vector `y(t)`.
    /// * `lags`: A mutable reference to an array of lags, where the computed lags should be stored.
    ///
    fn lags(&self, t: T, y: &Y, lags: &mut [T; L]);
}