LaTeX support for argmin-testfunctions docs

.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+rustdocflags = [ "--html-in-header", "./crates/argmin-testfunctions/katex-header.html" ]

.github/workflows/book.yml

@@ -33,3 +33,6 @@ jobs:
       - name: Test code samples
         working-directory: ./media/book/tests
         run: cargo test
+        env:
+          # Override value in workspace top-level Cargo config.toml
+          RUSTDOCFLAGS: ''

.github/workflows/ci.yml

@@ -92,6 +92,9 @@ jobs:
 
   tests-argmin-math:
     runs-on: ubuntu-latest
+    env:
+      # Override value in workspace top-level Cargo config.toml
+      RUSTDOCFLAGS: ''
     steps:
       - uses: actions/checkout@v4
       - uses: Swatinem/rust-cache@v2

crates/argmin-testfunctions/Cargo.toml

@@ -12,6 +12,9 @@ readme = "README.md"
 keywords = ["test", "function", "optimization"]
 categories = ["science"]
 
+[package.metadata.docs.rs]
+rustdoc-args = [ "--html-in-header", "katex-header.html" ]
+
 [dependencies]
 num = "0.4"
 

crates/argmin-testfunctions/katex-header.html

@@ -0,0 +1,13 @@
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" integrity="sha384-7zkQWkzuo3B5mTepMUcHkMB5jZaolc2xDwL6VFqjFALcbeS9Ggm/Yr2r3Dy4lfFg" crossorigin="anonymous"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk" crossorigin="anonymous"></script>
+<script>
+    document.addEventListener("DOMContentLoaded", function() {
+        renderMathInElement(document.body, {
+            delimiters: [
+                {left: "$$", right: "$$", display: true},
+                {left: "$", right: "$", display: false},
+            ]
+        });
+    });
+</script>

crates/argmin-testfunctions/src/ackley.rs

@@ -9,12 +9,14 @@
 //!
 //! Defined as
 //!
-//! `f(x_1, x_2, ..., x_n) = - a * exp( -b \sqrt{\frac{1}{d}\sum_{i=1}^n x_i^2 ) -
-//! exp( \frac{1}{d} cos(c * x_i) ) + a + exp(1)`
+//! $$
+//! f(x_1, x_2, ..., x_n) = -a\exp\left(-b\sqrt{\frac{1}{n}\sum_{i=1}^{n}x_i^2}\right) -
+//! \exp\left(\frac{1}{n}\sum_{i=1}^{n}\cos(cx_i)\right) + a + \exp(1)
+//! $$
 //!
-//! where `x_i \in [-32.768, 32.768]` and usually `a = 10`, `b = 0.2` and `c = 2*pi`
+//! where $x_i \in [-32.768,\\,32.768]$ and usually $a = 20$, $b = 0.2$ and $c = 2\pi$.
 //!
-//! The global minimum is at `f(x_1, x_2, ..., x_n) = f(0, 0, ..., 0) = 0`.
+//! The global minimum is at $f(x_1, x_2, ..., x_n) = f(0, 0, ..., 0) = 0$.
 
 use num::{Float, FromPrimitive};
 use std::f64::consts::PI;
@@ -24,12 +26,14 @@ use std::iter::Sum;
 ///
 /// Defined as
 ///
-/// `f(x_1, x_2, ..., x_n) = - a * exp( -b \sqrt{\frac{1}{d}\sum_{i=1}^n x_i^2 ) -
-/// exp( \frac{1}{d} cos(c * x_i) ) + a + exp(1)`
+/// $$
+/// f(x_1, x_2, ..., x_n) = -a\exp\left(-b\sqrt{\frac{1}{n}\sum_{i=1}^{n}x_i^2}\right) -
+/// \exp\left(\frac{1}{n}\sum_{i=1}^{n}\cos(cx_i)\right) + a + \exp(1)
+/// $$
 ///
-/// where `x_i \in [-32.768, 32.768]` and usually `a = 10`, `b = 0.2` and `c = 2*pi`
+/// where $x_i \in [-32.768,\\,32.768]$ and usually $a = 20$, $b = 0.2$ and $c = 2\pi$.
 ///
-/// The global minimum is at `f(x_1, x_2, ..., x_n) = f(0, 0, ..., 0) = 0`.
+/// The global minimum is at $f(x_1, x_2, ..., x_n) = f(0, 0, ..., 0) = 0$.
 pub fn ackley<T>(param: &[T]) -> T
 where
     T: Float + FromPrimitive + Sum,
@@ -44,7 +48,7 @@ where
 
 /// Ackley test function
 ///
-/// The same as `ackley`; however, it allows to set the parameters a, b and c.
+/// The same as [`ackley`]; however, it allows to set the parameters $a$, $b$ and $c$.
 pub fn ackley_abc<T>(param: &[T], a: T, b: T, c: T) -> T
 where
     T: Float + FromPrimitive + Sum,
@@ -59,7 +63,7 @@ where
 
 /// Derivative of Ackley test function
 ///
-/// Calls `ackley_abc_derivative` with `a = 10`, `b = 0.2` and `c = 2*pi`
+/// Calls [`ackley_abc_derivative`] with $a = 20$, $b = 0.2$ and $c = 2\pi$.
 pub fn ackley_derivative<T>(param: &[T]) -> Vec<T>
 where
     T: Float + FromPrimitive + Sum,
@@ -74,7 +78,7 @@ where
 
 /// Derivative of Ackley test function
 ///
-/// The same as `ackley_derivative`; however, it allows to set the parameters a, b and c.
+/// The same as [`ackley_derivative`]; however, it allows to set the parameters $a$, $b$ and $c$.
 pub fn ackley_abc_derivative<T>(param: &[T], a: T, b: T, c: T) -> Vec<T>
 where
     T: Float + FromPrimitive + Sum,
@@ -100,7 +104,7 @@ where
 
 /// Derivative of Ackley test function
 ///
-/// Calls `ackley_abc_derivative_const` with `a = 10`, `b = 0.2` and `c = 2*pi`
+/// Calls [`ackley_abc_derivative_const`] with $a = 20$, $b = 0.2$ and $c = 2\pi$.
 ///
 /// This is the const generics version, which requires the number of parameters to be known
 /// at compile time.
@@ -118,7 +122,7 @@ where
 
 /// Derivative of Ackley test function
 ///
-/// The same as `ackley_derivative`; however, it allows to set the parameters a, b and c.
+/// The same as [`ackley_derivative`]; however, it allows to set the parameters $a$, $b$ and $c$.
 ///
 /// This is the const generics version, which requires the number of parameters to be known
 /// at compile time.
@@ -151,7 +155,7 @@ where
 
 /// Hessian of Ackley test function
 ///
-/// Calls `ackley_abc_hessian` with `a = 10`, `b = 0.2` and `c = 2*pi`
+/// Calls [`ackley_abc_hessian`] with $a = 20$, $b = 0.2$ and $c = 2\pi$.
 pub fn ackley_hessian<T>(param: &[T]) -> Vec<Vec<T>>
 where
     T: Float + FromPrimitive + Sum + std::fmt::Debug,
@@ -166,7 +170,7 @@ where
 
 /// Hessian of Ackley test function
 ///
-/// The same as `ackley_hessian`; however, it allows to set the parameters a, b and c.
+/// The same as [`ackley_hessian`]; however, it allows to set the parameters $a$, $b$ and $c$.
 pub fn ackley_abc_hessian<T>(param: &[T], a: T, b: T, c: T) -> Vec<Vec<T>>
 where
     T: Float + FromPrimitive + Sum,
@@ -216,7 +220,7 @@ where
 
 /// Hessian of Ackley test function
 ///
-/// Calls `ackley_abc_hessian` with `a = 10`, `b = 0.2` and `c = 2*pi`
+/// Calls [`ackley_abc_hessian`] with $a = 20$, $b = 0.2$ and $c = 2\pi$.
 ///
 /// This is the const generics version, which requires the number of parameters to be known
 /// at compile time.
@@ -234,7 +238,7 @@ where
 
 /// Hessian of Ackley test function
 ///
-/// The same as `ackley_hessian`; however, it allows to set the parameters a, b and c.
+/// The same as [`ackley_hessian`]; however, it allows to set the parameters $a$, $b$ and $c$.
 pub fn ackley_abc_hessian_const<const N: usize, T>(param: &[T; N], a: T, b: T, c: T) -> [[T; N]; N]
 where
     T: Float + FromPrimitive + Sum,

crates/argmin-testfunctions/src/beale.rs

@@ -9,25 +9,29 @@
 //!
 //! Defined as
 //!
-//! `f(x_1, x_2) = (1.5 - x_1 + x_1 * x_2)^2 + (2.25 - x_1 + x_1 * x_2^2)^2 +
-//!                (2.625 - x_1 + x1 * x_2^3)^2`
+//! $$
+//! f(x_1, x_2) = (1.5 - x_1 + x_1 x_2)^2 + (2.25 - x_1 + x_1 x_2^2)^2 +
+//!               (2.625 - x_1 + x_1 x_2^3)^2
+//! $$
 //!
-//! where `x_i \in [-4.5, 4.5]`.
+//! where $x_i \in [-4.5,\\,4.5]$.
 //!
-//! The global minimum is at `f(x_1, x_2) = f(3, 0.5) = 0`.
+//! The global minimum is at $f(x_1, x_2) = f(3, 0.5) = 0$.
 
 use num::{Float, FromPrimitive};
 
 /// Beale test function
 ///
 /// Defined as
 ///
-/// `f(x_1, x_2) = (1.5 - x_1 + x_1 * x_2)^2 + (2.25 - x_1 + x_1 * x_2^2)^2 +
-///                (2.625 - x_1 + x_1 * x_2^3)^2`
+/// $$
+/// f(x_1, x_2) = (1.5 - x_1 + x_1 x_2)^2 + (2.25 - x_1 + x_1 x_2^2)^2 +
+///               (2.625 - x_1 + x_1 x_2^3)^2
+/// $$
 ///
-/// where `x_i \in [-4.5, 4.5]`.
+/// where $x_i \in [-4.5,\\,4.5]$.
 ///
-/// The global minimum is at `f(x_1, x_2) = f(3, 0.5) = 0`.
+/// The global minimum is at $f(x_1, x_2) = f(3, 0.5) = 0$.
 pub fn beale<T>(param: &[T; 2]) -> T
 where
     T: Float + FromPrimitive,
@@ -76,7 +80,7 @@ where
     ]
 }
 
-/// Derivative of Beale test function
+/// Hessian of Beale test function
 pub fn beale_hessian<T>(param: &[T; 2]) -> [[T; 2]; 2]
 where
     T: Float + FromPrimitive,

crates/argmin-testfunctions/src/booth.rs

@@ -9,23 +9,27 @@
 //!
 //! Defined as
 //!
-//! `f(x_1, x_2) = (x_1 + 2*x_2 - 7)^2 + (2*x_1 + x_2 - 5)^2`
+//! $$
+//! f(x_1, x_2) = (x_1 + 2x_2 - 7)^2 + (2x_1 + x_2 - 5)^2
+//! $$
 //!
-//! where `x_i \in [-10, 10]`.
+//! where $x_i \in [-10,\\,10]$.
 //!
-//! The global minimum is at `f(x_1, x_2) = f(1, 3) = 0`.
+//! The global minimum is at $f(x_1, x_2) = f(1, 3) = 0$.
 
 use num::{Float, FromPrimitive};
 
 /// Booth test function
 ///
 /// Defined as
 ///
-/// `f(x_1, x_2) = (x_1 + 2*x_2 - 7)^2 + (2*x_1 + x_2 - 5)^2
+/// $$
+/// f(x_1, x_2) = (x_1 + 2x_2 - 7)^2 + (2x_1 + x_2 - 5)^2
+/// $$
 ///
-/// where `x_i \in [-10, 10]`.
+/// where $x_i \in [-10,\\,10]$.
 ///
-/// The global minimum is at `f(x_1, x_2) = f(1, 3) = 0`.
+/// The global minimum is at $f(x_1, x_2) = f(1, 3) = 0$.
 pub fn booth<T>(param: &[T; 2]) -> T
 where
     T: Float + FromPrimitive,
@@ -55,7 +59,7 @@ where
 
 /// Hessian of Booth test function
 ///
-/// Returns [[10, 8], [8, 10]] for every input.
+/// Returns $\left(\begin{matrix}10 & 8\\\\8 & 10\end{matrix}\right)$ for every input.
 pub fn booth_hessian<T>(_param: &[T; 2]) -> [[T; 2]; 2]
 where
     T: Float + FromPrimitive,

crates/argmin-testfunctions/src/bukin.rs

@@ -9,23 +9,27 @@
 //!
 //! Defined as
 //!
-//! `f(x_1, x_2) = 100*\sqrt{|x_2 - 0.01*x_1^2|} + 0.01 * |x_1 + 10|`
+//! $$
+//! f(x_1, x_2) = 100\sqrt{\left|x_2 - 0.01x_1^2\right|} + 0.01\left|x_1 + 10\right|
+//! $$
 //!
-//! where `x_1 \in [-15, -5]` and `x_2 \in [-3, 3]`.
+//! where $x_1 \in [-15,\\,-5]$ and $x_2 \in [-3,\\,3]$.
 //!
-//! The global minimum is at `f(x_1, x_2) = f(-10, 1) = 0`.
+//! The global minimum is at $f(x_1, x_2) = f(-10, 1) = 0$.
 
 use num::{Float, FromPrimitive};
 
 /// Bukin test function No. 6
 ///
 /// Defined as
 ///
-/// `f(x_1, x_2) = 100*\sqrt{|x_2 - 0.01*x_1^2|} + 0.01 * |x_1 + 10|`
+/// $$
+/// f(x_1, x_2) = 100\sqrt{\left|x_2 - 0.01x_1^2\right|} + 0.01\left|x_1 + 10\right|
+/// $$
 ///
-/// where `x_1 \in [-15, -5]` and `x_2 \in [-3, 3]`.
+/// where $x_1 \in [-15,\\,-5]$ and $x_2 \in [-3,\\,3]$.
 ///
-/// The global minimum is at `f(x_1, x_2) = f(-10, 1) = 0`.
+/// The global minimum is at $f(x_1, x_2) = f(-10, 1) = 0$.
 pub fn bukin_n6<T>(param: &[T; 2]) -> T
 where
     T: Float + FromPrimitive,

crates/argmin-testfunctions/src/crossintray.rs

@@ -9,16 +9,19 @@
 //!
 //! Defined as
 //!
-//! `f(x_1, x_2) = -0.0001 * ( | sin(x_1)*sin(x_2)*exp(| 100 -
-//!                                                      \sqrt{x_1^2+x_2^2} / pi |) | + 1)^0.1`
+//! $$
+//! f(x_1, x_2) = -0.0001\left(\left|\sin(x_1)\sin(x_2)
+//!               \exp\left(\left| 100 - \frac{\sqrt{x_1^2+x_2^2}}{\pi} \right|\right)\right| +
+//!               1\right)^{0.1}
+//! $$
 //!
-//! where `x_i \in [-10, 10]`.
+//! where $x_i \in [-10,\\,10]$.
 //!
 //! The global minima are at
-//!  * `f(x_1, x_2) = f(1.34941, 1.34941) = -2.06261`.
-//!  * `f(x_1, x_2) = f(1.34941, -1.34941) = -2.06261`.
-//!  * `f(x_1, x_2) = f(-1.34941, 1.34941) = -2.06261`.
-//!  * `f(x_1, x_2) = f(-1.34941, -1.34941) = -2.06261`.
+//!  * $f(x_1, x_2) = f(1.34941, 1.34941) = -2.06261$.
+//!  * $f(x_1, x_2) = f(1.34941, -1.34941) = -2.06261$.
+//!  * $f(x_1, x_2) = f(-1.34941, 1.34941) = -2.06261$.
+//!  * $f(x_1, x_2) = f(-1.34941, -1.34941) = -2.06261$.
 
 use std::f64::consts::PI;
 
@@ -28,18 +31,21 @@ use num::{Float, FromPrimitive};
 ///
 /// Defined as
 ///
-/// `f(x_1, x_2) = -0.0001 * ( | sin(x_1)*sin(x_2)*exp(| 100 -
-///                                                      \sqrt{x_1^2+x_2^2} / pi |) | + 1)^0.1`
+/// $$
+/// f(x_1, x_2) = -0.0001\left(\left|\sin(x_1)\sin(x_2)
+///               \exp\left(\left| 100 - \frac{\sqrt{x_1^2+x_2^2}}{\pi} \right|\right)\right| +
+///               1\right)^{0.1}
+/// $$
 ///
-/// where `x_i \in [-10, 10]`.
+/// where $x_i \in [-10,\\,10]$.
 ///
 /// The global minima are at
-///  * `f(x_1, x_2) = f(1.34941, 1.34941) = -2.06261`.
-///  * `f(x_1, x_2) = f(1.34941, -1.34941) = -2.06261`.
-///  * `f(x_1, x_2) = f(-1.34941, 1.34941) = -2.06261`.
-///  * `f(x_1, x_2) = f(-1.34941, -1.34941) = -2.06261`.
+///  * $f(x_1, x_2) = f(1.34941, 1.34941) = -2.06261$.
+///  * $f(x_1, x_2) = f(1.34941, -1.34941) = -2.06261$.
+///  * $f(x_1, x_2) = f(-1.34941, 1.34941) = -2.06261$.
+///  * $f(x_1, x_2) = f(-1.34941, -1.34941) = -2.06261$.
 ///
-/// Note: Even if the input parameters are f32, internal computations will be performed in f64.
+/// Note: Even if the input parameters are [`f32`], internal computations will be performed in [`f64`].
 pub fn cross_in_tray<T>(param: &[T; 2]) -> T
 where
     T: Float + Into<f64> + FromPrimitive,
@@ -58,7 +64,7 @@ where
 
 /// Derivative of Cross-in-tray test function
 ///
-/// Note: Even if the input parameters are f32, internal computations will be performed in f64.
+/// Note: Even if the input parameters are [`f32`], internal computations will be performed in [`f64`].
 pub fn cross_in_tray_derivative<T>(param: &[T; 2]) -> [T; 2]
 where
     T: Float + Into<f64> + FromPrimitive,
@@ -111,9 +117,9 @@ where
 
 /// Hessian of Cross-in-tray test function
 ///
-/// This function may return NaN or INF.
+/// This function may return [NAN][f64::NAN] or [INFINITY][f64::INFINITY].
 ///
-/// Note: Even if the input parameters are f32, internal computations will be performed in f64.
+/// Note: Even if the input parameters are [`f32`], internal computations will be performed in [`f64`].
 pub fn cross_in_tray_hessian<T>(param: &[T; 2]) -> [[T; 2]; 2]
 where
     T: Float + Into<f64> + FromPrimitive,

crates/argmin-testfunctions/src/easom.rs

@@ -9,11 +9,13 @@
 //!
 //! Defined as
 //!
-//! `f(x_1, x_2) = - cos(x_1) * cos(x_2) * exp(-(x_1 - pi)^2 - (x_2 - pi)^2)`
+//! $$
+//! f(x_1, x_2) = - \cos(x_1)\cos(x_2)\exp\left(-(x_1 - \pi)^2 - (x_2 - \pi)^2\right)
+//! $$
 //!
-//! where `x_i \in [-100, 100]`.
+//! where $x_i \in [-100,\\,100]$.
 //!
-//! The global minimum is at `f(x_1, x_2) = f(pi, pi) = -1`.
+//! The global minimum is at $f(x_1, x_2) = f(\pi, \pi) = -1$.
 
 use num::{Float, FromPrimitive};
 use std::f64::consts::PI;
@@ -22,11 +24,13 @@ use std::f64::consts::PI;
 ///
 /// Defined as
 ///
-/// `f(x_1, x_2) = - cos(x_1) * cos(x_2) * exp(-(x_1 - pi)^2 - (x_2 - pi)^2)`
+/// $$
+/// f(x_1, x_2) = - \cos(x_1)\cos(x_2)\exp\left(-(x_1 - \pi)^2 - (x_2 - \pi)^2\right)
+/// $$
 ///
-/// where `x_i \in [-100, 100]`.
+/// where $x_i \in [-100,\\,100]$.
 ///
-/// The global minimum is at `f(x_1, x_2) = f(pi, pi) = -1`.
+/// The global minimum is at $f(x_1, x_2) = f(\pi, \pi) = -1$.
 pub fn easom<T>(param: &[T; 2]) -> T
 where
     T: Float + FromPrimitive,