scirs2_integrate/analysis/
types.rs

1//! Core data structures for dynamical systems analysis
2//!
3//! This module contains all the fundamental types used for bifurcation analysis,
4//! stability assessment, and related dynamical systems analysis.
5
6use crate::error::{IntegrateError, IntegrateResult, Result};
7use scirs2_core::ndarray::{Array1, Array2};
8use scirs2_core::numeric::Complex64;
9use std::collections::HashMap;
10
11/// Bifurcation point information
12#[derive(Debug, Clone)]
13pub struct BifurcationPoint {
14    /// Parameter value at bifurcation
15    pub parameter_value: f64,
16    /// State at bifurcation
17    pub state: Array1<f64>,
18    /// Type of bifurcation
19    pub bifurcation_type: BifurcationType,
20    /// Eigenvalues at bifurcation point
21    pub eigenvalues: Vec<Complex64>,
22}
23
24/// Types of bifurcations
25#[derive(Debug, Clone, PartialEq, Eq, Hash)]
26pub enum BifurcationType {
27    /// Fold/saddle-node bifurcation
28    Fold,
29    /// Transcritical bifurcation
30    Transcritical,
31    /// Pitchfork bifurcation
32    Pitchfork,
33    /// Hopf bifurcation (birth of limit cycle)
34    Hopf,
35    /// Period-doubling bifurcation
36    PeriodDoubling,
37    /// Homoclinic bifurcation
38    Homoclinic,
39    /// Unknown/unclassified bifurcation
40    Unknown,
41    /// Cusp bifurcation (codimension-2)
42    Cusp,
43    /// Takens-Bogdanov bifurcation
44    TakensBogdanov,
45    /// Bautin bifurcation (generalized Hopf)
46    Bautin,
47    /// Zero-Hopf bifurcation
48    ZeroHopf,
49    /// Double-Hopf bifurcation
50    DoubleHopf,
51}
52
53/// Stability assessment result
54#[derive(Debug, Clone)]
55pub struct StabilityResult {
56    /// Fixed points found
57    pub fixed_points: Vec<FixedPoint>,
58    /// Periodic orbits found
59    pub periodic_orbits: Vec<PeriodicOrbit>,
60    /// Lyapunov exponents
61    pub lyapunov_exponents: Option<Array1<f64>>,
62    /// Basin of attraction estimates
63    pub basin_analysis: Option<BasinAnalysis>,
64}
65
66/// Fixed point information
67#[derive(Debug, Clone)]
68pub struct FixedPoint {
69    /// Location of fixed point
70    pub location: Array1<f64>,
71    /// Stability type
72    pub stability: StabilityType,
73    /// Eigenvalues of linearization
74    pub eigenvalues: Vec<Complex64>,
75    /// Eigenvectors of linearization
76    pub eigenvectors: Array2<Complex64>,
77}
78
79/// Periodic orbit information
80#[derive(Debug, Clone)]
81pub struct PeriodicOrbit {
82    /// Representative point on orbit
83    pub representative_point: Array1<f64>,
84    /// Period of orbit
85    pub period: f64,
86    /// Stability type
87    pub stability: StabilityType,
88    /// Floquet multipliers
89    pub floquet_multipliers: Vec<Complex64>,
90}
91
92/// Stability classification
93#[derive(Debug, Clone, PartialEq)]
94pub enum StabilityType {
95    /// Stable (attracting)
96    Stable,
97    /// Unstable (repelling)
98    Unstable,
99    /// Saddle (mixed stability)
100    Saddle,
101    /// Center (neutrally stable)
102    Center,
103    /// Degenerate (requires higher-order analysis)
104    Degenerate,
105    /// Spiral stable
106    SpiralStable,
107    /// Spiral unstable
108    SpiralUnstable,
109    /// Node stable
110    NodeStable,
111    /// Node unstable
112    NodeUnstable,
113    /// Marginally stable
114    Marginally,
115}
116
117/// Basin of attraction analysis
118#[derive(Debug, Clone)]
119pub struct BasinAnalysis {
120    /// Grid points analyzed
121    pub grid_points: Array2<f64>,
122    /// Attractor index for each grid point (-1 for divergent)
123    pub attractor_indices: Array2<i32>,
124    /// List of attractors found
125    pub attractors: Vec<Array1<f64>>,
126}
127
128/// Two-parameter bifurcation analysis result
129#[derive(Debug, Clone)]
130pub struct TwoParameterBifurcationResult {
131    /// Parameter grid
132    pub parameter_grid: Array2<f64>,
133    /// Stability classification at each grid point
134    pub stability_map: Array2<f64>,
135    /// Detected bifurcation curves
136    pub bifurcation_curves: Vec<BifurcationCurve>,
137    /// Parameter 1 range
138    pub parameter_range_1: (f64, f64),
139    /// Parameter 2 range
140    pub parameter_range_2: (f64, f64),
141}
142
143/// Bifurcation curve in parameter space
144#[derive(Debug, Clone)]
145pub struct BifurcationCurve {
146    /// Points on the curve
147    pub points: Vec<(f64, f64)>,
148    /// Type of bifurcation
149    pub curve_type: BifurcationType,
150}
151
152/// Continuation result
153#[derive(Debug, Clone)]
154pub struct ContinuationResult {
155    /// Solution branch
156    pub solution_branch: Vec<Array1<f64>>,
157    /// Parameter values along branch
158    pub parameter_values: Vec<f64>,
159    /// Whether continuation converged
160    pub converged: bool,
161    /// Final residual
162    pub final_residual: f64,
163}
164
165/// Sensitivity analysis result
166#[derive(Debug, Clone)]
167pub struct SensitivityAnalysisResult {
168    /// First-order sensitivities with respect to each parameter
169    pub first_order_sensitivities: HashMap<String, Array1<f64>>,
170    /// Parameter interaction effects (second-order)
171    pub parameter_interactions: HashMap<(String, String), Array1<f64>>,
172    /// Nominal parameter values
173    pub nominal_parameters: HashMap<String, f64>,
174    /// Nominal state
175    pub nominal_state: Array1<f64>,
176}
177
178/// Normal form analysis result
179#[derive(Debug, Clone)]
180pub struct NormalFormResult {
181    /// Coefficients of the normal form
182    pub normal_form_coefficients: Array1<f64>,
183    /// Transformation matrix to normal form coordinates
184    pub transformation_matrix: Array2<f64>,
185    /// Type of normal form
186    pub normal_form_type: BifurcationType,
187    /// Stability analysis description
188    pub stability_analysis: String,
189}
scirs2_integrate/analysis/types.rs

scirs2_integrate/analysis/
types.rs
