diff --git a/diffsol/src/context/mod.rs b/diffsol/src/context/mod.rs index 0ab2a38b..e5c1f63e 100644 --- a/diffsol/src/context/mod.rs +++ b/diffsol/src/context/mod.rs @@ -1,3 +1,9 @@ +//! Context objects for managing device resources for vectors and matrices (e.g. device streams, threading pools, etc.). +//! +//! This module provides context types that encapsulate where data is stored and computed (CPU, GPU, etc.). +//! Different backends like nalgebra and faer may require different context implementations. The [`Context`] +//! trait defines the interface that must be implemented. + use crate::{DefaultDenseMatrix, Matrix, Vector}; #[cfg(feature = "cuda")] diff --git a/diffsol/src/error.rs b/diffsol/src/error.rs index a47e4ee0..54c0276e 100644 --- a/diffsol/src/error.rs +++ b/diffsol/src/error.rs @@ -1,3 +1,8 @@ +//! Error types and handling. +//! +//! This module defines the [`DiffsolError`] enum and specialized error variants for different failure modes +//! in ODE solving, including parsing, compilation, and numerical errors. + use faer::sparse::CreationError; use thiserror::Error; diff --git a/diffsol/src/jacobian/mod.rs b/diffsol/src/jacobian/mod.rs index 60d91500..3daa9179 100644 --- a/diffsol/src/jacobian/mod.rs +++ b/diffsol/src/jacobian/mod.rs @@ -1,3 +1,12 @@ +//! Jacobian computation and coloring algorithms for efficient Jacobian evaluation. +//! +//! This module provides utilities for: +//! - Detecting the sparsity pattern of Jacobian matrices using NaN propagation +//! - Computing efficient graph colorings of the Jacobian sparsity pattern +//! - Using the coloring to compute sparse Jacobians with fewer function evaluations +//! +//! The [`JacobianColoring`] struct is the main entry point for computing Jacobians efficiently. + use std::collections::HashSet; use crate::{ diff --git a/diffsol/src/lib.rs b/diffsol/src/lib.rs index dadc0965..f496bffc 100644 --- a/diffsol/src/lib.rs +++ b/diffsol/src/lib.rs @@ -142,122 +142,26 @@ pub use diffsl::CraneliftJitModule; #[cfg(feature = "diffsl-llvm")] pub use diffsl::LlvmModule; -/// Context objects for managing device resources for vectors and matrices (e.g. device streams, threading pools, etc.). -/// -/// This module provides context types that encapsulate information about where data is stored and computed -/// (CPU, GPU, etc.). Different backends like nalgebra and faer may require different context implementations. -/// The [Context] trait defines the interface that must be implemented. pub mod context; -/// Jacobian computation and coloring algorithms for efficient Jacobian evaluation. -/// -/// This module provides utilities for: -/// - Detecting the sparsity pattern of Jacobian matrices using NaN propagation -/// - Computing efficient graph colorings of the Jacobian sparsity pattern -/// - Using the coloring to compute sparse Jacobians with fewer function evaluations -/// -/// The [JacobianColoring] struct is the main entry point for computing Jacobians efficiently. pub mod jacobian; -/// Linear solver implementations and traits. -/// -/// This module defines the [LinearSolver] trait for solving linear systems and provides implementations: -/// - Direct solvers: [NalgebraLU], [FaerLU], [FaerSparseLU] -/// - Optional sparse solvers: `KLU` (requires `suitesparse` feature) -/// - GPU solvers: `CudaLU` (requires `cuda` feature) -/// -/// The linear solver is a critical component used internally by nonlinear solvers to solve Newton systems. pub mod linear_solver; -/// Matrix types and operations. -/// -/// This module defines the [Matrix] trait and related traits for matrix operations: -/// - [DenseMatrix] for dense column-major matrices -/// - [MatrixView] and [MatrixViewMut] for borrowed views -/// - Sparsity detection and handling -/// -/// Implementations are provided for: -/// - Dense matrices: [NalgebraMat], [FaerMat] -/// - Sparse matrices: [FaerSparseMat] -/// - GPU matrices: `CudaMat` (requires `cuda` feature) pub mod matrix; -/// Nonlinear solver implementations and traits. -/// -/// This module defines the [NonLinearSolver] trait and provides the [NewtonNonlinearSolver] implementation. -/// It also includes: -/// - [LineSearch] implementations for globalization ([NoLineSearch], [BacktrackingLineSearch]) -/// - Root finding algorithms via [RootFinder] -/// - Convergence testing via [Convergence] -/// -/// Nonlinear solvers are used internally by ODE solvers to solve implicit equations. pub mod nonlinear_solver; -/// ODE equations and traits. -/// -/// This module defines the [OdeEquations] trait and specialized variants: -/// - [OdeEquationsImplicit] for implicit ODEs with mass matrices -/// - [OdeEquationsImplicitSens] for forward sensitivity equations -/// - [OdeEquationsAdjoint] for adjoint sensitivity equations -/// -/// It also provides implementations: -/// - [DiffSl] for equations specified in the DiffSL domain-specific language -/// - [SensEquations] and [AdjointEquations] for sensitivity computations -/// -/// All the test equations used in Diffsol's test suite are also provided here. pub mod ode_equations; -/// ODE solver implementations and traits. -/// -/// This module provides the complete ODE solving interface including: -/// - [OdeSolverMethod] trait with implementations: [Bdf], [Sdirk], [ExplicitRk] -/// - [OdeSolverProblem] for problem setup (equations, parameters, tolerances, solver options etc.) -/// - [OdeSolverState] for managing solution state (including state vector, sensitivities, time, step size etc.) -/// - [OdeBuilder] for convenient problem construction (builds and configures [OdeSolverProblem]) -/// - [Checkpointing] and [HermiteInterpolator] for solution interpolation pub mod ode_solver; -/// Operator types and traits (e.g. non-linear, linear and constant operators; as well as their jacobians). -/// -/// This module defines fundamental operator traits, for example: -/// - [NonLinearOp] and variants for Jacobians and sensitivities -/// - [LinearOp] for linear operators -/// - [ConstantOp] for constants -/// -/// It also provides concrete implementations, for example: -/// - [Closure] for wrapping user-provided closures -/// - [LinearClosure] for linear operators -/// - [ConstantClosure] for constants -/// - [MatrixOp] for explicit matrix operators pub mod op; -/// Scalar types and traits. -/// -/// This module defines the [Scalar] trait that all floating-point types used in DiffSol must implement. -/// It aggregates requirements from nalgebra, faer, and num_traits to ensure compatibility with linear algebra operations. -/// -/// Implementations are provided for `f32` and `f64`. -/// GPU scalar types are available via `ScalarCuda` (requires `cuda` feature). pub mod scalar; -/// Vector types and traits. -/// -/// This module defines the [Vector] trait and related traits for vector operations: -/// - [VectorView] and [VectorViewMut] for borrowed views -/// - [VectorIndex] for index collections -/// - [VectorHost] for CPU-resident vectors with direct access -/// -/// Implementations are provided for: -/// - [NalgebraVec] using nalgebra vectors -/// - [FaerVec] using faer vectors -/// - `CudaVec` for GPU computation (requires `cuda` feature) pub mod vector; -/// Error types and handling. -/// -/// This module defines the [DiffsolError] enum and specialized error variants -/// for different failure modes in ODE solving, including parsing, compilation, -/// and numerical errors. pub mod error; pub use error::DiffsolError; diff --git a/diffsol/src/linear_solver/mod.rs b/diffsol/src/linear_solver/mod.rs index c847156a..a9d73d61 100644 --- a/diffsol/src/linear_solver/mod.rs +++ b/diffsol/src/linear_solver/mod.rs @@ -1,3 +1,12 @@ +//! Linear solver implementations and traits. +//! +//! This module defines the [`LinearSolver`] trait for solving linear systems and provides implementations: +//! - Direct solvers: [`NalgebraLU`], [`FaerLU`], [`FaerSparseLU`](crate::FaerSparseLU) +//! - Optional sparse solvers: `KLU` (requires the `suitesparse` feature) +//! - GPU solvers: `CudaLU` (requires the `cuda` feature) +//! +//! The linear solver is a critical component used internally by nonlinear solvers to solve Newton systems. + use crate::{error::DiffsolError, Matrix, NonLinearOpJacobian}; #[cfg(feature = "nalgebra")] diff --git a/diffsol/src/matrix/mod.rs b/diffsol/src/matrix/mod.rs index 1de88e2d..b1475463 100644 --- a/diffsol/src/matrix/mod.rs +++ b/diffsol/src/matrix/mod.rs @@ -1,3 +1,15 @@ +//! Matrix types and operations. +//! +//! This module defines the [`Matrix`] trait and related traits for matrix operations: +//! - [`DenseMatrix`] for dense column-major matrices +//! - [`MatrixView`] and [`MatrixViewMut`] for borrowed views +//! - Sparsity detection and handling +//! +//! Implementations are provided for: +//! - Dense matrices: [`NalgebraMat`](crate::NalgebraMat), [`FaerMat`](crate::FaerMat) +//! - Sparse matrices: [`FaerSparseMat`](crate::FaerSparseMat) +//! - GPU matrices: `CudaMat` (requires the `cuda` feature) + use std::fmt::Debug; use std::ops::{Add, AddAssign, Mul, MulAssign, Sub, SubAssign}; diff --git a/diffsol/src/nonlinear_solver/mod.rs b/diffsol/src/nonlinear_solver/mod.rs index a8d7c392..a51a1f86 100644 --- a/diffsol/src/nonlinear_solver/mod.rs +++ b/diffsol/src/nonlinear_solver/mod.rs @@ -1,3 +1,13 @@ +//! Nonlinear solver implementations and traits. +//! +//! This module defines the [`NonLinearSolver`] trait and provides the [`NewtonNonlinearSolver`](crate::NewtonNonlinearSolver) implementation. +//! It also includes: +//! - [`LineSearch`](crate::nonlinear_solver::line_search::LineSearch) implementations for globalization ([`NoLineSearch`](crate::NoLineSearch), [`BacktrackingLineSearch`](crate::BacktrackingLineSearch)) +//! - Root finding algorithms via [`RootFinder`](crate::nonlinear_solver::root::RootFinder) +//! - Convergence testing via [`Convergence`] +//! +//! Nonlinear solvers are used internally by ODE solvers to solve implicit equations. + use crate::{error::DiffsolError, Matrix, NonLinearOp, NonLinearOpJacobian}; use convergence::Convergence; diff --git a/diffsol/src/ode_equations/mod.rs b/diffsol/src/ode_equations/mod.rs index 6c2e51d4..8c9f4c3f 100644 --- a/diffsol/src/ode_equations/mod.rs +++ b/diffsol/src/ode_equations/mod.rs @@ -1,3 +1,16 @@ +//! ODE equations and traits. +//! +//! This module defines the [`OdeEquations`] trait and specialized variants: +//! - [`OdeEquationsImplicit`] for implicit ODEs with mass matrices +//! - [`OdeEquationsImplicitSens`] for forward sensitivity equations +//! - [`OdeEquationsAdjoint`] for adjoint sensitivity equations +//! +//! It also provides implementations: +//! - [`DiffSl`](crate::DiffSl) for equations specified in the DiffSL domain-specific language +//! - [`SensEquations`](crate::ode_equations::sens_equations::SensEquations) and [`AdjointEquations`](crate::ode_equations::adjoint_equations::AdjointEquations) for sensitivity computations +//! +//! All the test equations used in Diffsol's test suite are also provided here. + use crate::{ op::{constant_op::ConstantOpSensAdjoint, linear_op::LinearOpTranspose, ParameterisedOp}, ConstantOp, ConstantOpSens, LinearOp, Matrix, NonLinearOp, NonLinearOpAdjoint, diff --git a/diffsol/src/ode_solver/mod.rs b/diffsol/src/ode_solver/mod.rs index d65767ec..069dbb8a 100644 --- a/diffsol/src/ode_solver/mod.rs +++ b/diffsol/src/ode_solver/mod.rs @@ -1,3 +1,12 @@ +//! ODE solver implementations and traits. +//! +//! This module provides the complete ODE solving interface including: +//! - [`OdeSolverMethod`](crate::OdeSolverMethod) trait with implementations: [`Bdf`](crate::Bdf), [`Sdirk`](crate::Sdirk), [`ExplicitRk`](crate::ExplicitRk) +//! - [`OdeSolverProblem`](crate::OdeSolverProblem) for problem setup (equations, parameters, tolerances, solver options etc.) +//! - [`OdeSolverState`](crate::OdeSolverState) for managing solution state (including state vector, sensitivities, time, step size etc.) +//! - [`OdeBuilder`](crate::OdeBuilder) for convenient problem construction (builds and configures [`OdeSolverProblem`](crate::OdeSolverProblem)) +//! - [`Checkpointing`](crate::Checkpointing) and [`HermiteInterpolator`](crate::HermiteInterpolator) for solution interpolation + pub mod adjoint; pub mod bdf; pub mod bdf_state; diff --git a/diffsol/src/op/mod.rs b/diffsol/src/op/mod.rs index 177e711f..f3380437 100644 --- a/diffsol/src/op/mod.rs +++ b/diffsol/src/op/mod.rs @@ -1,3 +1,16 @@ +//! Operator types and traits (e.g. non-linear, linear and constant operators; as well as their Jacobians). +//! +//! This module defines fundamental operator traits, for example: +//! - [`NonLinearOp`] and variants for Jacobians and sensitivities +//! - [`LinearOp`] for linear operators +//! - [`ConstantOp`] for constants +//! +//! It also provides concrete implementations, for example: +//! - [`closure::Closure`] for wrapping user-provided closures +//! - [`linear_closure::LinearClosure`] for linear operators +//! - [`constant_closure::ConstantClosure`] for constants +//! - [`matrix::MatrixOp`] for explicit matrix operators + use crate::{ ConstantOp, ConstantOpSens, ConstantOpSensAdjoint, Context, LinearOp, LinearOpTranspose, Matrix, NonLinearOp, NonLinearOpAdjoint, NonLinearOpSens, NonLinearOpSensAdjoint, Scalar, diff --git a/diffsol/src/scalar/mod.rs b/diffsol/src/scalar/mod.rs index 68400fd3..38c931ef 100644 --- a/diffsol/src/scalar/mod.rs +++ b/diffsol/src/scalar/mod.rs @@ -1,3 +1,10 @@ +//! Scalar types and traits. +//! +//! This module defines the [`Scalar`] trait that all floating-point types used in Diffsol must implement. +//! It aggregates requirements from nalgebra, faer, and num_traits to ensure compatibility with linear algebra operations. +//! +//! Implementations are provided for `f32` and `f64`. GPU scalar types are available via `ScalarCuda` (requires the `cuda` feature). + use std::{ fmt::Display, ops::{Add, AddAssign, Mul, MulAssign, Sub, SubAssign}, diff --git a/diffsol/src/vector/mod.rs b/diffsol/src/vector/mod.rs index 8d04c4ce..d6c9408f 100644 --- a/diffsol/src/vector/mod.rs +++ b/diffsol/src/vector/mod.rs @@ -1,3 +1,15 @@ +//! Vector types and traits. +//! +//! This module defines the [`Vector`] trait and related traits for vector operations: +//! - [`VectorView`] and [`VectorViewMut`] for borrowed views +//! - [`VectorIndex`] for index collections +//! - [`VectorHost`] for CPU-resident vectors with direct access +//! +//! Implementations are provided for: +//! - [`NalgebraVec`](crate::NalgebraVec) using nalgebra vectors +//! - [`FaerVec`](crate::FaerVec) using faer vectors +//! - `CudaVec` for GPU computation (requires the `cuda` feature) + use crate::matrix::DenseMatrix; use crate::scalar::Scale; use crate::{Context, IndexType, Scalar}; diff --git a/examples/neural-ode-weather-prediction/neural-ode-weather_1 b/examples/neural-ode-weather-prediction/neural-ode-weather_1 new file mode 100644 index 00000000..7026fabd --- /dev/null +++ b/examples/neural-ode-weather-prediction/neural-ode-weather_1 @@ -0,0 +1,4 @@ +
+ \ No newline at end of file