Documentations for ODEs with KaTeX

Cargo.toml

@@ -14,7 +14,7 @@ readme        = "README.md"
 
 [features]
 default   = []
-oss       = ["ndarray-linalg/openblas-static",  "fftw/source"]
+oss       = ["ndarray-linalg/openblas-static", "fftw/source"]
 intel-mkl = ["ndarray-linalg/intel-mkl-static", "fftw/intel-mkl"]
 
 [dependencies]
@@ -24,6 +24,8 @@ derive-new  = { version = "0.5.9", default-features = false }
 ndarray     = { version = "0.15.6", default-features = false }
 fftw        = { version = "0.8.0", default-features = false }
 
+katexit = "0.1.4"
+
 [dependencies.ndarray-linalg]
 version = "0.16.0"
 default-features = false

src/ode/goy_shell.rs

@@ -1,18 +1,49 @@
-//! GOY-shell model
-
 use ndarray::*;
 use num_complex::Complex64 as c64;
 use num_traits::{PrimInt, Zero};
 
 use crate::traits::*;
 
+#[cfg_attr(doc, katexit::katexit)]
+/// GOY-shell model, a simple model for energy cascade in turbulence
+///
+/// $$
+/// \left(\frac{d}{dt} + \nu k^2_n \right)u_n =
+/// ik_n \left(
+///     a_n u_{n+1}^* u_{n+2}^*
+///     + \frac{1}{2} b_n u_{n-1}^* u_{n+1}^*
+///     + \frac{1}{4} c_n u_{n-1}^* u_{n-2}^*
+/// \right) + f \delta_{n,m}
+/// $$
+///
+/// where
+/// - $n \in [0, N-1]$
+/// - $k_n = k_0 2^n$
+/// - $u_n \in \mathbb{C}$ and $u_n^*$ means its complex conjugate.
+/// - $\delta_{n, m}$ means $1$ if $n = m$ and $0$ otherwise.
+/// - $a_n = 1, b_n = -\epsilon, c_n = -(1-\epsilon)$ where $\epsilon$
+///   represents the energy transfer within the cascade.
+///
+/// This is also an example for stiff equation
+/// since $k_n^2$ are exponentially large.
+///
+/// Links
+/// -----
+/// - ["Transition to chaos in a shell model of turbulence", L. Biferale et al.](https://doi.org/10.1016/0167-2789(95)90065-9)
+///
 #[derive(Clone, Copy, Debug)]
 pub struct GoyShell {
+    /// $N$, system size
     size: usize,
+    /// $\nu$, the viscosity
     nu: f64,
+    /// $\epsilon$, Energy transfer parameter
     e: f64,
+    /// $k_0$, Base wave number
     k0: f64,
+    /// Amplitude of external energy input
     f: f64,
+    /// $m$, the wave number of external energy input
     f_idx: usize,
 }
 

src/ode/lorenz63.rs

@@ -1,10 +1,22 @@
-//! Lorenz three-variables system
-//! https://en.wikipedia.org/wiki/Lorenz_system
-
 use ndarray::*;
 
 use crate::traits::*;
 
+#[cfg_attr(doc, katexit::katexit)]
+/// Lorenz three-variables system, "The chaotic attractor"
+///
+/// $$
+/// \begin{align*}
+///   \frac{dx}{dt} &= r(y-x) \\\\
+///   \frac{dy}{dt} &= x(p-z) -y \\\\
+///   \frac{dz}{dt} &= xy - bz
+/// \end{align*}
+/// $$
+/// $(p, r, b)= (10, 28, 8/3)$ is original and commonly used parameter.
+///
+/// Links
+/// ------
+/// - Wikipedia <https://en.wikipedia.org/wiki/Lorenz_system>
 #[derive(Clone, Copy, Debug)]
 pub struct Lorenz63 {
     pub p: f64,

src/ode/lorenz96.rs

@@ -1,12 +1,23 @@
-//! Lorenz 96 model
-//! https://en.wikipedia.org/wiki/Lorenz_96_model
-
 use crate::traits::*;
 use ndarray::*;
 
+#[cfg_attr(doc, katexit::katexit)]
+/// Lorenz 96 model, frequently used on [data assimilation](https://en.wikipedia.org/wiki/Data_assimilation) community.
+///
+/// $$
+/// \frac{dx_i}{dt} = (x_{i+1}-x_{i-2}) x_{i-1} - x_{i} + F
+/// $$
+/// where $i \in [0, n-1]$ and cyclic boundary condition, i.e. $x_{n + i} = x_i$ is used.
+/// $F = 8$ is used commonly to produce chaotic behavior.
+///
+/// Links
+/// ------
+/// - Wikipedia <https://en.wikipedia.org/wiki/Lorenz_96_model>
 #[derive(Clone, Copy, Debug)]
 pub struct Lorenz96 {
+    /// $F$ in the equation, default is $8.0$
     pub f: f64,
+    /// Number of elements, default is $40$
     pub n: usize,
 }
 

src/ode/mod.rs

@@ -1,9 +1,9 @@
 //! Example nonlinear ODEs
 
-pub mod goy_shell;
-pub mod lorenz63;
-pub mod lorenz96;
-pub mod roessler;
+mod goy_shell;
+mod lorenz63;
+mod lorenz96;
+mod roessler;
 
 pub use self::goy_shell::GoyShell;
 pub use self::lorenz63::Lorenz63;

src/ode/roessler.rs

@@ -1,13 +1,28 @@
-//! Roessler system
-//! https://en.wikipedia.org/wiki/Lorenz_syste://en.wikipedia.org/wiki/R%C3%B6ssler_attractor
-
 use crate::traits::*;
 use ndarray::*;
 
+#[cfg_attr(doc, katexit::katexit)]
+/// Rössler system
+///
+/// $$
+/// \begin{align*}
+///   \frac{dx}{dt} &= -y-z \\\\
+///   \frac{dy}{dt} &= x + ay \\\\
+///   \frac{dz}{dt} &= b + z(x-c)
+/// \end{align*}
+/// $$
+/// The original parameter by Rössler is $(a,b,c) = (0.2, 0.2, 5.7)$.
+///
+/// Links
+/// ------
+/// - Wikipedia <https://en.wikipedia.org/wiki/R%C3%B6ssler_attractor>
 #[derive(Clone, Copy, Debug)]
 pub struct Roessler {
+    /// default is $0.2$
     pub a: f64,
+    /// default is $0.2$
     pub b: f64,
+    /// default is $5.7$
     pub c: f64,
 }