1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
//! Numerical methods for solving differential equations
//!
//! This module contains concrete implementations of the [`Solver`](crate::solver::Solver) trait.
//!
//! # Architecture
//!
//! The separation between abstract solver interface (`solver::traits`) and concrete
//! implementations (`solver::methods`) follows the Open-Closed Principle:
//! - **Open** for extension: Add new methods without modifying existing code
//! - **Closed** for modification: The `Solver` trait is stable and never changes
//!
//! # Available Methods
//!
//! ## Explicit Time-Stepping Methods
//!
//! These methods are suitable for non-stiff ordinary differential equations (ODEs)
//! where the right-hand side function can be evaluated explicitly.
//!
//! - **[`EulerSolver`]**: Forward Euler method
//! - Order: First-order O(dt)
//! - Cost: 1 function evaluation per step
//! - Use: Prototyping, educational purposes, non-stiff problems with relaxed accuracy
//!
//! - **[`RK4Solver`]**: Classical fourth-order Runge-Kutta
//! - Order: Fourth-order O(dt⁴)
//! - Cost: 4 function evaluations per step
//! - Use: **Production simulations**, non-stiff to moderately stiff problems
//!
//! # Future Methods (Planned)
//!
//! ## Adaptive Methods (v0.2.0+)
//! - **RK45**: Runge-Kutta-Fehlberg with adaptive step size control
//! - **Dormand-Prince**: Higher-order adaptive method
//!
//! ## Implicit Methods (v0.3.0+)
//! - **BDF**: Backward Differentiation Formulas for stiff problems
//! - **Rosenbrock**: Semi-implicit methods
//!
//! ## Iterative Methods (v0.4.0+)
//! - **Newton-Raphson**: For steady-state problems
//! - **GMRES**: For large linear systems
//!
//! # Example
//!
//! ```rust
//! use chrom_rs::solver::{EulerSolver, RK4Solver};
//! use chrom_rs::solver::{Scenario, DomainBoundaries, Solver, SolverConfiguration};
//! use chrom_rs::physics::{ PhysicalModel, PhysicalState, PhysicalQuantity, PhysicalData };
//! use nalgebra::DVector;
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(Deserialize, Serialize)]
//! struct MyModel;
//!
//! #[typetag::serde]
//! impl PhysicalModel for MyModel {
//! fn points(&self) -> usize { 1 }
//! fn compute_physics(&self, state: &PhysicalState, _ctx: &chrom_rs::physics::ComputeContext) -> PhysicalState { state.clone() }
//! fn setup_initial_state(&self) -> PhysicalState {
//! PhysicalState::new(PhysicalQuantity::Concentration, PhysicalData::Vector(DVector::from_vec(vec![1.0])))
//! }
//! fn name(&self) -> &str { "MyModel" }
//! }
//!
//! fn main() -> Result<(), String> {
//!
//! let model = Box::new(MyModel);
//! let boundaries = DomainBoundaries::temporal(model.setup_initial_state());
//! let scenario = Scenario::new(model, boundaries);
//!
//!
//! // Using Euler for production
//! let euler = EulerSolver::new();
//! let configuration = SolverConfiguration::time_evolution(600.0, 10000);
//! let result = euler.solve(&scenario, &configuration)?;
//!
//! // Using Runge-Kutta for production
//! let rk4 = RK4Solver::new();
//! let configuration = SolverConfiguration::time_evolution(600.0, 10000);
//! let result = euler.solve(&scenario, &configuration)?;
//!
//! Ok(())
//! }
//!
//! ```
//!
//! # Design Philosophy
//!
//! Each solver is:
//! - **Self-contained**: No shared mutable state
//! - **Stateless**: Can be reused for multiple simulations
//! - **Well-tested**: 30+ tests per solver with ~95% coverage
//! - **Documented**: Complete rustdoc with mathematical background
//!
//! # Performance Considerations
//!
//! All solvers benefit from:
//! - **Rayon parallelization** (feature `parallel`) for large spatial grids
//! - **Configurable threshold** via `set_parallel_threshold()`
//! - **Efficient nalgebra** operations for matrix arithmetic
//!
//! See individual solver documentation for specific performance characteristics.
// Re-exports for convenience
pub use EulerSolver;
pub use RK4Solver;