docs: Add examples for Solver/System traits

These were previously in the module docs for corresponding modules, but
they were made private during a later restructuring.

src/core/solver.rs

@@ -1,74 +1,72 @@
-//! Abstractions for solvers.
-//!
-//! All solvers implement a common interface defined by the [`Solver`] trait.
-//! The essential method is [`next`](Solver::next) which takes variables *x* and
-//! computes the next step. Thus it represents one iteration in the process.
-//! Repeated call to this method should converge *x* to the solution in
-//! successful cases.
-//!
-//! If you implement a solver, please consider make it a contribution to this
-//! library.
-//!
-//! # Implementing a solver
-//!
-//! Here is an implementation of a random solver (if such a thing can be called
-//! a solver) which randomly generates values in a hope that a solution can be
-//! found with enough luck.
-//!
-//! ```rust
-//! use gomez::nalgebra as na;
-//! use gomez::core::{Domain, Solver, System, SystemError};
-//! use na::{storage::StorageMut, Vector};
-//! use rand::Rng;
-//! use rand_distr::{uniform::SampleUniform, Distribution, Uniform};
-//!
-//! struct Random<R> {
-//!     rng: R,
-//! }
-//!
-//! impl<R> Random<R> {
-//!     fn new(rng: R) -> Self {
-//!         Self { rng }
-//!     }
-//! }
-//!
-//! impl<F: System, R: Rng> Solver<F> for Random<R>
-//! where
-//!     F::Scalar: SampleUniform,
-//! {
-//!     const NAME: &'static str = "Random";
-//!     type Error = SystemError;
-//!
-//!     fn next<Sx, Sfx>(
-//!         &mut self,
-//!         f: &F,
-//!         dom: &Domain<F::Scalar>,
-//!         x: &mut Vector<F::Scalar, F::Dim, Sx>,
-//!         fx: &mut Vector<F::Scalar, F::Dim, Sfx>,
-//!     ) -> Result<(), Self::Error>
-//!     where
-//!         Sx: StorageMut<F::Scalar, F::Dim>,
-//!         Sfx: StorageMut<F::Scalar, F::Dim>,
-//!     {
-//!         // Randomly sample within the bounds.
-//!         x.iter_mut().zip(dom.vars().iter()).for_each(|(xi, vi)| {
-//!             *xi = Uniform::new_inclusive(vi.lower(), vi.upper()).sample(&mut self.rng)
-//!         });
-//!
-//!         // We must compute the residuals.
-//!         f.apply_mut(x, fx)?;
-//!
-//!         Ok(())
-//!     }
-//! }
-//! ```
-
 use nalgebra::{storage::StorageMut, Vector};
 
 use super::domain::Domain;
 use super::system::System;
 
 /// Common interface for all solvers.
+///
+/// All solvers implement a common interface defined by the [`Solver`] trait.
+/// The essential method is [`next`](Solver::next) which takes variables *x* and
+/// computes the next step. Thus it represents one iteration in the process.
+/// Repeated call to this method should converge *x* to the solution in
+/// successful cases.
+///
+/// If you implement a solver, please consider make it a contribution to this
+/// library.
+///
+/// ## Implementing a solver
+///
+/// Here is an implementation of a random solver (if such a thing can be called
+/// a solver) which randomly generates values in a hope that a solution can be
+/// found with enough luck.
+///
+/// ```rust
+/// use gomez::nalgebra as na;
+/// use gomez::core::{Domain, Solver, System, SystemError};
+/// use na::{storage::StorageMut, Vector};
+/// use rand::Rng;
+/// use rand_distr::{uniform::SampleUniform, Distribution, Uniform};
+///
+/// struct Random<R> {
+///     rng: R,
+/// }
+///
+/// impl<R> Random<R> {
+///     fn new(rng: R) -> Self {
+///         Self { rng }
+///     }
+/// }
+///
+/// impl<F: System, R: Rng> Solver<F> for Random<R>
+/// where
+///     F::Scalar: SampleUniform,
+/// {
+///     const NAME: &'static str = "Random";
+///     type Error = SystemError;
+///
+///     fn next<Sx, Sfx>(
+///         &mut self,
+///         f: &F,
+///         dom: &Domain<F::Scalar>,
+///         x: &mut Vector<F::Scalar, F::Dim, Sx>,
+///         fx: &mut Vector<F::Scalar, F::Dim, Sfx>,
+///     ) -> Result<(), Self::Error>
+///     where
+///         Sx: StorageMut<F::Scalar, F::Dim>,
+///         Sfx: StorageMut<F::Scalar, F::Dim>,
+///     {
+///         // Randomly sample within the bounds.
+///         x.iter_mut().zip(dom.vars().iter()).for_each(|(xi, vi)| {
+///             *xi = Uniform::new_inclusive(vi.lower(), vi.upper()).sample(&mut self.rng)
+///         });
+///
+///         // We must compute the residuals.
+///         f.apply_mut(x, fx)?;
+///
+///         Ok(())
+///     }
+/// }
+/// ```
 pub trait Solver<F: System> {
     /// Name of the solver.
     const NAME: &'static str;

src/core/system.rs

@@ -1,52 +1,3 @@
-//! Abstractions and types for defining equation systems.
-//!
-//! # Defining a system
-//!
-//! A system is any type that implements [`System`] trait. There are two
-//! required associated types (scalar type and dimension type) and two required
-//! methods: [`apply_mut`](System::apply_mut) and [`dim`](System::dim).
-//!
-//! ```rust
-//! use gomez::nalgebra as na;
-//! use gomez::prelude::*;
-//! use na::{Dim, DimName};
-//!
-//! // A problem is represented by a type.
-//! struct Rosenbrock {
-//!     a: f64,
-//!     b: f64,
-//! }
-//!
-//! impl System for Rosenbrock {
-//!     // The numeric type. Usually f64 or f32.
-//!     type Scalar = f64;
-//!     // The dimension of the problem. Can be either statically known or dynamic.
-//!     type Dim = na::U2;
-//!
-//!     // Apply trial values of variables to the system.
-//!     fn apply_mut<Sx, Sfx>(
-//!         &self,
-//!         x: &na::Vector<Self::Scalar, Self::Dim, Sx>,
-//!         fx: &mut na::Vector<Self::Scalar, Self::Dim, Sfx>,
-//!     ) -> Result<(), SystemError>
-//!     where
-//!         Sx: na::storage::Storage<Self::Scalar, Self::Dim>,
-//!         Sfx: na::storage::StorageMut<Self::Scalar, Self::Dim>,
-//!     {
-//!         // Compute the residuals of all equations.
-//!         fx[0] = (self.a - x[0]).powi(2);
-//!         fx[1] = self.b * (x[1] - x[0].powi(2)).powi(2);
-//!
-//!         Ok(())
-//!     }
-//!
-//!     // Return the actual dimension of the system.
-//!     fn dim(&self) -> Self::Dim {
-//!         na::U2::name()
-//!     }
-//! }
-//! ```
-
 use nalgebra::{
     allocator::Allocator,
     storage::{Storage, StorageMut},
@@ -73,6 +24,53 @@ pub enum SystemError {
 }
 
 /// The trait for defining equations systems.
+///
+/// ## Defining a system
+///
+/// A system is any type that implements [`System`] trait. There are two
+/// required associated types (scalar type and dimension type) and two required
+/// methods: [`apply_mut`](System::apply_mut) and [`dim`](System::dim).
+///
+/// ```rust
+/// use gomez::nalgebra as na;
+/// use gomez::prelude::*;
+/// use na::{Dim, DimName};
+///
+/// // A problem is represented by a type.
+/// struct Rosenbrock {
+///     a: f64,
+///     b: f64,
+/// }
+///
+/// impl System for Rosenbrock {
+///     // The numeric type. Usually f64 or f32.
+///     type Scalar = f64;
+///     // The dimension of the problem. Can be either statically known or dynamic.
+///     type Dim = na::U2;
+///
+///     // Apply trial values of variables to the system.
+///     fn apply_mut<Sx, Sfx>(
+///         &self,
+///         x: &na::Vector<Self::Scalar, Self::Dim, Sx>,
+///         fx: &mut na::Vector<Self::Scalar, Self::Dim, Sfx>,
+///     ) -> Result<(), SystemError>
+///     where
+///         Sx: na::storage::Storage<Self::Scalar, Self::Dim>,
+///         Sfx: na::storage::StorageMut<Self::Scalar, Self::Dim>,
+///     {
+///         // Compute the residuals of all equations.
+///         fx[0] = (self.a - x[0]).powi(2);
+///         fx[1] = self.b * (x[1] - x[0].powi(2)).powi(2);
+///
+///         Ok(())
+///     }
+///
+///     // Return the actual dimension of the system.
+///     fn dim(&self) -> Self::Dim {
+///         na::U2::name()
+///     }
+/// }
+/// ```
 pub trait System {
     /// Type of the scalar, usually f32 or f64.
     type Scalar: RealField;