From 90f8c6593a57dda7b6217411da1a3895aeff5f27 Mon Sep 17 00:00:00 2001
From: HugoMVale <57530119+HugoMVale@users.noreply.github.com>
Date: Sun, 5 May 2024 23:13:33 +0200
Subject: [PATCH] doc

---
 docs/reference/kinetics/Arrhenius.md          | 20 -----------
 docs/reference/kinetics/Eyring.md             | 20 -----------
 .../kinetics/PropagationHalfLength.md         | 15 --------
 .../kinetics/TerminationCompositeModel.md     | 14 --------
 docs/reference/math/RootResult.md             |  6 ++++
 docs/reference/utils/types.md                 |  1 +
 mkdocs.yml                                    |  5 +--
 src/polykin/kinetics/arrhenius.py             | 16 +++++++--
 src/polykin/kinetics/cldpropagation.py        | 34 ++++++++++++++++---
 src/polykin/kinetics/cldtermination.py        | 31 ++++++++++++++---
 src/polykin/kinetics/eyring.py                | 16 +++++++--
 src/polykin/math/derivatives.py               |  5 +--
 src/polykin/math/solvers.py                   | 20 ++++++-----
 13 files changed, 108 insertions(+), 95 deletions(-)
 create mode 100644 docs/reference/math/RootResult.md

diff --git a/docs/reference/kinetics/Arrhenius.md b/docs/reference/kinetics/Arrhenius.md
index 7c9b240..9dcc136 100644
--- a/docs/reference/kinetics/Arrhenius.md
+++ b/docs/reference/kinetics/Arrhenius.md
@@ -4,23 +4,3 @@
     options:
         members:
             - Arrhenius
-
-## Examples
-
-Define and evaluate the propagation rate coefficient of styrene.
-
-```python exec="on" source="material-block"
-from polykin.kinetics import Arrhenius
-
-kp = Arrhenius(
-    10**7.63,               # pre-exponential factor
-    32.5e3/8.314,           # Ea/R, K
-    Tmin=261.,
-    Tmax=366.,
-    symbol='k_p',
-    unit='L/mol/s',
-    name='kp of styrene'
-    )
-
-print(f"kp = {kp(25.,'C'):.1f} " + kp.unit)
-```
diff --git a/docs/reference/kinetics/Eyring.md b/docs/reference/kinetics/Eyring.md
index b0b702c..b0db244 100644
--- a/docs/reference/kinetics/Eyring.md
+++ b/docs/reference/kinetics/Eyring.md
@@ -4,23 +4,3 @@
     options:
         members:
             - Eyring
-
-## Examples
-
-Define and evaluate a rate coefficient from transition state properties.
-
-```python exec="on" source="material-block"
-from polykin.kinetics import Eyring
-
-k = Eyring(
-    DSa=20.,        # activation entropy
-    DHa=5e4,        # activation entropy
-    kappa=0.8,      # transmission factor
-    Tmin=273.,
-    Tmax=373.,
-    symbol='k',
-    name='A->B'
-    )
-
-print(f"k = {k(25.,'C'):.2e} " + k.unit)
-```
diff --git a/docs/reference/kinetics/PropagationHalfLength.md b/docs/reference/kinetics/PropagationHalfLength.md
index b575931..d4a47ea 100644
--- a/docs/reference/kinetics/PropagationHalfLength.md
+++ b/docs/reference/kinetics/PropagationHalfLength.md
@@ -4,18 +4,3 @@
     options:
         members:
             - PropagationHalfLength
-
-## Examples
-
-```python exec="on" source="material-block"
-from polykin.kinetics import PropagationHalfLength, Arrhenius
-
-kp = Arrhenius(
-    10**7.63, 32.5e3/8.314, Tmin=261., Tmax=366., symbol='k_p',
-    unit='L/mol/s', name='kp of styrene')
-
-kpi = PropagationHalfLength(kp, C=10, ihalf=0.5, name='kp(T,i) of styrene')
-
-# kp of a trimeric radical at 50°C
-print(f"{kpi(T=50., i=3, Tunit='C'):.2e} " + kp.unit)
-```
diff --git a/docs/reference/kinetics/TerminationCompositeModel.md b/docs/reference/kinetics/TerminationCompositeModel.md
index 3ae02cd..721e651 100644
--- a/docs/reference/kinetics/TerminationCompositeModel.md
+++ b/docs/reference/kinetics/TerminationCompositeModel.md
@@ -4,17 +4,3 @@
     options:
         members:
             - TerminationCompositeModel
-
-## Examples
-
-```python exec="on" source="material-block"
-from polykin.kinetics import TerminationCompositeModel, Arrhenius
-
-kt11 = Arrhenius(1e9, 2e3, T0=298., symbol='k_t(T,1,1)', unit='L/mol/s',
-                name='kt11 of Y')
-
-ktij = TerminationCompositeModel(kt11, icrit=30, name='ktij of Y')
-
-# kt between radicals with chain lengths 150 and 200 at 25°C
-print(f"{ktij(T=25., i=150, j=200, Tunit='C'):.2e} " + kt11.unit)
-```
diff --git a/docs/reference/math/RootResult.md b/docs/reference/math/RootResult.md
new file mode 100644
index 0000000..d276aab
--- /dev/null
+++ b/docs/reference/math/RootResult.md
@@ -0,0 +1,6 @@
+# polykin.math
+
+::: polykin.math.solvers
+    options:
+        members:
+            - RootResult
diff --git a/docs/reference/utils/types.md b/docs/reference/utils/types.md
index 843a1f5..eb0dfc5 100644
--- a/docs/reference/utils/types.md
+++ b/docs/reference/utils/types.md
@@ -7,6 +7,7 @@
             - FloatArrayLike
             - FloatVector
             - FloatVectorLike
+            - Float2x2Matrix
             - FloatMatrix
             - FloatSquareMatrix
             - FloatRangeArray
diff --git a/mkdocs.yml b/mkdocs.yml
index 6a2c466..b243c7b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -54,7 +54,7 @@ watch:
 plugins:
   - search
   - autolinks
-  # - autorefs
+  - autorefs
   - markdown-exec
   - table-reader
   #- bibtex:
@@ -215,8 +215,9 @@ nav:
           - derivative_centered: reference/math/derivative_centered.md
           - derivative_complex: reference/math/derivative_complex.md
           - hessian2: reference/math/hessian2.md
-          - root_secant: reference/math/root_secant.md
           - root_newton: reference/math/root_newton.md
+          - root_secant: reference/math/root_secant.md
+          - RootResult: reference/math/RootResult.md
       - polykin.properties:
           - reference/properties/index.md
           - Equations: reference/properties/equations/index.md
diff --git a/src/polykin/kinetics/arrhenius.py b/src/polykin/kinetics/arrhenius.py
index 78494a3..6d62771 100644
--- a/src/polykin/kinetics/arrhenius.py
+++ b/src/polykin/kinetics/arrhenius.py
@@ -9,13 +9,12 @@
 import numpy as np
 from numpy import exp
 
+from polykin.kinetics.base import KineticCoefficientT
 from polykin.utils.exceptions import ShapeError
 from polykin.utils.math import convert_FloatOrArrayLike_to_FloatOrArray
 from polykin.utils.tools import check_bounds, check_shapes
 from polykin.utils.types import FloatArray, FloatArrayLike
 
-from .base import KineticCoefficientT
-
 __all__ = ['Arrhenius']
 
 
@@ -62,6 +61,19 @@ class Arrhenius(KineticCoefficientT):
     --------
     * [`Eyring`](Eyring.md): alternative method.
 
+    Examples
+    --------
+    Define and evaluate the propagation rate coefficient of styrene.
+    >>> from polykin.kinetics import Arrhenius 
+    >>> kp = Arrhenius(
+    ...     10**7.63,       # pre-exponential factor
+    ...     32.5e3/8.314,   # Ea/R, K
+    ...     Tmin=261., Tmax=366.,
+    ...     symbol='k_p',
+    ...     unit='L/mol/s',
+    ...     name='kp of styrene')
+    >>> kp(25.,'C') 
+    86.28385101961442
     """
 
     _pinfo = {'k0': ('#', True), 'EaR': ('K', True), 'T0': ('K', False)}
diff --git a/src/polykin/kinetics/cldpropagation.py b/src/polykin/kinetics/cldpropagation.py
index 0bfa176..ea3bd90 100644
--- a/src/polykin/kinetics/cldpropagation.py
+++ b/src/polykin/kinetics/cldpropagation.py
@@ -7,15 +7,14 @@
 import numpy as np
 from numpy import exp, log
 
+from polykin.kinetics.arrhenius import Arrhenius
+from polykin.kinetics.base import KineticCoefficientCLD
+from polykin.kinetics.eyring import Eyring
 from polykin.utils.tools import (check_bounds, check_type,
                                  convert_check_temperature, custom_repr)
 from polykin.utils.types import (FloatArray, FloatArrayLike, IntArray,
                                  IntArrayLike)
 
-from .arrhenius import Arrhenius
-from .base import KineticCoefficientCLD
-from .eyring import Eyring
-
 __all__ = ['PropagationHalfLength']
 
 
@@ -50,6 +49,31 @@ class PropagationHalfLength(KineticCoefficientCLD):
         Half-length, $i_{1/2}$.
     name : str
         Name.
+
+    Examples
+    --------
+    >>> from polykin.kinetics import PropagationHalfLength, Arrhenius
+    >>> kp = Arrhenius(
+    ...    10**7.63, 32.5e3/8.314, Tmin=261., Tmax=366.,
+    ...    symbol='k_p', unit='L/mol/s', name='kp of styrene')
+
+    >>> kpi = PropagationHalfLength(kp, C=10, ihalf=0.5,
+    ...    name='kp(T,i) of styrene')
+    >>> kpi
+    name:    kp(T,i) of styrene
+    C:       10
+    ihalf:   0.5
+    kp:
+      name:            kp of styrene
+      symbol:          k_p
+      unit:            L/mol/s
+      Trange [K]:      (261.0, 366.0)
+      k0 [L/mol/s]:    42657951.88015926
+      EaR [K]:         3909.0690401732018
+      T0 [K]:          inf
+
+    >>> kpi(T=50., i=3, Tunit='C')
+    371.75986615653215
     """
 
     kp: Union[Arrhenius, Eyring]
@@ -59,7 +83,7 @@ class PropagationHalfLength(KineticCoefficientCLD):
 
     def __init__(self,
                  kp: Union[Arrhenius, Eyring],
-                 C: float = 10.,
+                 C: float = 10.0,
                  ihalf: float = 1.0,
                  name: str = ''
                  ) -> None:
diff --git a/src/polykin/kinetics/cldtermination.py b/src/polykin/kinetics/cldtermination.py
index f3add3a..5f269c2 100644
--- a/src/polykin/kinetics/cldtermination.py
+++ b/src/polykin/kinetics/cldtermination.py
@@ -7,15 +7,14 @@
 import numpy as np
 from numpy import sqrt
 
+from polykin.kinetics.arrhenius import Arrhenius
+from polykin.kinetics.base import KineticCoefficientCLD
+from polykin.kinetics.eyring import Eyring
 from polykin.utils.tools import (check_bounds, check_type,
                                  convert_check_temperature, custom_repr)
 from polykin.utils.types import (FloatArray, FloatArrayLike, IntArray,
                                  IntArrayLike)
 
-from .arrhenius import Arrhenius
-from .base import KineticCoefficientCLD
-from .eyring import Eyring
-
 __all__ = ['TerminationCompositeModel']
 
 
@@ -58,6 +57,30 @@ class TerminationCompositeModel(KineticCoefficientCLD):
         Long-chain exponent, $\alpha_L$.
     name : str
         Name.
+
+    Examples
+    --------
+    >>> from polykin.kinetics import TerminationCompositeModel, Arrhenius
+    >>> kt11 = Arrhenius(1e9, 2e3, T0=298.,
+    ...        symbol='k_t(T,1,1)', unit='L/mol/s', name='kt11 of Y')
+
+    >>> ktij = TerminationCompositeModel(kt11, icrit=30, name='ktij of Y')
+    >>> ktij
+    name:    ktij of Y
+    icrit:   30
+    aS:      0.5
+    aL:      0.2
+    kt11:
+      name:            kt11 of Y
+      symbol:          k_t(T,1,1)
+      unit:            L/mol/s
+      Trange [K]:      (0.0, inf)
+      k0 [L/mol/s]:    1000000000.0
+      EaR [K]:         2000.0
+      T0 [K]:          298.0
+
+    >>> ktij(T=25., i=150, j=200, Tunit='C')
+    129008375.03821689
     """
 
     kt11: Union[Arrhenius, Eyring]
diff --git a/src/polykin/kinetics/eyring.py b/src/polykin/kinetics/eyring.py
index a1cc2f4..b890ddd 100644
--- a/src/polykin/kinetics/eyring.py
+++ b/src/polykin/kinetics/eyring.py
@@ -11,12 +11,11 @@
 from scipy.constants import Boltzmann as kB
 from scipy.constants import R, h
 
+from polykin.kinetics.base import KineticCoefficientT
 from polykin.utils.math import convert_FloatOrArrayLike_to_FloatOrArray
 from polykin.utils.tools import check_bounds, check_shapes
 from polykin.utils.types import FloatArray, FloatArrayLike
 
-from .base import KineticCoefficientT
-
 __all__ = ['Eyring']
 
 
@@ -61,6 +60,19 @@ class Eyring(KineticCoefficientT):
     --------
     * [`Arrhenius`](Arrhenius.md): alternative method.
 
+    Examples
+    --------
+    Define and evaluate a rate coefficient from transition state properties.
+    >>> from polykin.kinetics import Eyring 
+    >>> k = Eyring(
+    ...     DSa=20.,
+    ...     DHa=5e4,
+    ...     kappa=0.8,
+    ...     Tmin=273., Tmax=373.,
+    ...     symbol='k',
+    ...     name='A->B')
+    >>> k(25.,'C')
+    95808.36742009166
     """
 
     _pinfo = {'DSa': ('J/(mol·K)', True),
diff --git a/src/polykin/math/derivatives.py b/src/polykin/math/derivatives.py
index 90ffa58..ed95230 100644
--- a/src/polykin/math/derivatives.py
+++ b/src/polykin/math/derivatives.py
@@ -8,6 +8,7 @@
 from numpy import cbrt
 
 from polykin.utils.math import eps
+from polykin.utils.types import Float2x2Matrix
 
 __all__ = ['derivative_complex',
            'derivative_centered',
@@ -113,7 +114,7 @@ def derivative_centered(f: Callable[[float], float],
 def hessian2(f: Callable[[tuple[float, float]], float],
              x: tuple[float, float],
              h: Optional[float] = None
-             ) -> np.ndarray:
+             ) -> Float2x2Matrix:
     r"""Calculate the numerical Hessian of a scalar function $f(x,y)$ using the
     centered finite-difference scheme.
 
@@ -154,7 +155,7 @@ def hessian2(f: Callable[[tuple[float, float]], float],
 
     Returns
     -------
-    np.ndarray (2, 2)
+    Float2x2Matrix
         Hessian matrix.
 
     Examples
diff --git a/src/polykin/math/solvers.py b/src/polykin/math/solvers.py
index 505984f..0139f8a 100644
--- a/src/polykin/math/solvers.py
+++ b/src/polykin/math/solvers.py
@@ -39,11 +39,12 @@ def root_newton(f: Callable[[complex], complex],
                 ) -> RootResult:
     r"""Find the root of a scalar function using the newton method.
 
-    Unlike the equivalent method in scipy, this method uses complex step
-    differentiation to estimate the derivative of $f(x)$ without loss of
-    precision. Therefore, there is no need to provide $f'(x)$. It's application
-    is restricted to real functions that can be evaluated with complex inputs,
-    but which per se do not implement complex arithmetic.
+    Unlike the equivalent method in [scipy](https://docs.scipy.org/doc/scipy/reference/optimize.root_scalar-newton.html),
+    this method uses complex step differentiation to estimate the derivative of
+    $f(x)$ without loss of precision. Therefore, there is no need to provide
+    $f'(x)$. It's application is restricted to real functions that can be
+    evaluated with complex inputs, but which per se do not implement complex
+    arithmetic.
 
     Parameters
     ----------
@@ -62,7 +63,7 @@ def root_newton(f: Callable[[complex], complex],
 
     Returns
     -------
-    RootSolverResult
+    RootResult
         Dataclass with root solution results.
 
     Examples
@@ -104,8 +105,9 @@ def root_secant(f: Callable[[float], float],
                 ) -> RootResult:
     r"""Find the root of a scalar function using the secant method.
 
-    Unlike the equivalent method in scipy, this method also terminates based
-    on the function value. This is sometimes a more meaningful stop criterion.
+    Unlike the equivalent method in [scipy](https://docs.scipy.org/doc/scipy/reference/optimize.root_scalar-secant.html),
+    this method also terminates based on the function value. This is sometimes
+    a more meaningful stop criterion.
 
     Parameters
     ----------
@@ -126,7 +128,7 @@ def root_secant(f: Callable[[float], float],
 
     Returns
     -------
-    RootSolverResult
+    RootResult
         Dataclass with root solution results.
 
     Examples