Struct CrossingSolout

Source

pub struct CrossingSolout<T: Real> { /* private fields */ }

Expand description

A solout that detects when a component crosses a specified threshold value.

§Overview

CrossingSolout monitors a specific component of the state vector and detects when it crosses a defined threshold value. This is useful for identifying important events in the system’s behavior, such as:

Zero-crossings (by setting threshold to 0)
Detecting when a variable exceeds or falls below a critical value
Generating data for poincare sections or other analyses

The solout records the times and states when crossings occur, making them available in the solver output.

§Example

use differential_equations::prelude::*;
use differential_equations::solout::CrossingSolout;
use nalgebra::{Vector2, vector};

// Simple harmonic oscillator - position will cross zero periodically
struct HarmonicOscillator;

impl ODE<f64, Vector2<f64>> for HarmonicOscillator {
    fn diff(&self, _t: f64, y: &Vector2<f64>, dydt: &mut Vector2<f64>) {
        // y[0] = position, y[1] = velocity
        dydt[0] = y[1];
        dydt[1] = -y[0];
    }
}

// Create the system and solver
let system = HarmonicOscillator;
let t0 = 0.0;
let tf = 10.0;
let y0 = vector![1.0, 0.0]; // Start with positive position, zero velocity
let mut solver = ExplicitRungeKutta::dop853().rtol(1e-8).atol(1e-8);

// Detect zero-crossings of the position component (index 0)
let mut crossing_detector = CrossingSolout::new(0, 0.0);

// Solve and get only the crossing points
let problem = ODEProblem::new(system, t0, tf, y0);
let solution = problem.solout(&mut crossing_detector).solve(&mut solver).unwrap();

// solution now contains only the points where position crosses zero
println!("Zero crossings occurred at times: {:?}", solution.t);

§Directional Crossing Detection

You can filter the crossings by direction:

use differential_equations::solout::{CrossingSolout, CrossingDirection};

// Only detect positive crossings (from below to above threshold)
let positive_crossings = CrossingSolout::new(0, 5.0).with_direction(CrossingDirection::Positive);

// Only detect negative crossings (from above to below threshold)
let negative_crossings = CrossingSolout::new(0, 5.0).with_direction(CrossingDirection::Negative);

Implementations§

Source §

impl<T: Real> CrossingSolout<T>

Source

pub fn new(component_idx: usize, threshold: T) -> Self

Creates a new CrossingSolout to detect when the specified component crosses the threshold.

By default, crossings in both directions are detected.

§Arguments

component_idx - Index of the component in the state vector to monitor
threshold - The threshold value to detect crossings against

§Example

use differential_equations::solout::CrossingSolout;

// Detect when the first component (index 0) crosses the value 5.0
let detector = CrossingSolout::new(0, 5.0);

Source

pub fn with_direction(self, direction: CrossingDirection) -> Self

Set the direction of crossings to detect.

§Arguments

direction - The crossing direction to detect (Both, Positive, or Negative)

§Returns

Self - The modified CrossingSolout (builder pattern)

§Example

use differential_equations::solout::{CrossingSolout, CrossingDirection};

// Detect when the position (index 0) crosses zero in any direction
let any_crossing = CrossingSolout::new(0, 0.0).with_direction(CrossingDirection::Both);

// Detect when the position (index 0) goes from negative to positive
let zero_up_detector = CrossingSolout::new(0, 0.0).with_direction(CrossingDirection::Positive);

// Detect when the velocity (index 1) changes from positive to negative
let velocity_sign_change = CrossingSolout::new(1, 0.0).with_direction(CrossingDirection::Negative);

Source

pub fn positive_only(self) -> Self

Set to detect only positive crossings (from below to above threshold).

A positive crossing occurs when the monitored component transitions from a value less than the threshold to a value greater than or equal to the threshold.

§Returns

Self - The modified CrossingSolout (builder pattern)

§Example

use differential_equations::solout::CrossingSolout;

// Detect when the position (index 0) goes from negative to positive
let zero_up_detector = CrossingSolout::new(0, 0.0).positive_only();

Source

pub fn negative_only(self) -> Self

Set to detect only negative crossings (from above to below threshold).

A negative crossing occurs when the monitored component transitions from a value greater than the threshold to a value less than or equal to the threshold.

§Returns

Self - The modified CrossingSolout (builder pattern)

§Example

use differential_equations::solout::CrossingSolout;

// Detect when the velocity (index 1) changes from positive to negative
let velocity_sign_change = CrossingSolout::new(1, 0.0).negative_only();