From 09512487525e316c38762c870c514cafa7716f7f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20K=C3=B6hler?=
 <27728103+Ceyron@users.noreply.github.com>
Date: Wed, 10 Apr 2024 07:14:30 +0200
Subject: [PATCH] Add docs

---
 exponax/normalized/_linear.py | 91 ++++++++++++++++++++++++++++++++---
 1 file changed, 85 insertions(+), 6 deletions(-)

diff --git a/exponax/normalized/_linear.py b/exponax/normalized/_linear.py
index 4059261..043b618 100644
--- a/exponax/normalized/_linear.py
+++ b/exponax/normalized/_linear.py
@@ -17,13 +17,41 @@ def __init__(
         normalized_coefficients: tuple[float, ...] = (0.0, -0.5, 0.01),
     ):
         """
-        By default: advection-diffusion with normalized advection of 0.5, and
-        normalized diffusion of 0.01.
+        Timestepper for d-dimensional (`d ∈ {1, 2, 3}`) linear PDEs on periodic
+        boundary conditions with normalized dynamics.
+
+        If the PDE in physical description is
+
+            uₜ = ∑ᵢ aᵢ (∂ₓ)ⁱ u
+
+        with `aᵢ` the coefficients on `domain_extent` `L` with time step `dt`,
+        the normalized coefficients are
+
+            αᵢ = (aᵢ Δt)/(Lⁱ)
+
+        Important: note that the `domain_extent` is raised to the order of
+        linear derivative `i`.
+
+        One can also think of normalized dynamics, as a PDE on `domain_extent`
+        `1.0` with time step `dt=1.0`.
 
         Take care of the signs!
 
-        Normalized coefficients are alpha_i * dt / L^i, where dt is the time
-        step size and L is the domain extent.
+        In the defaulf configuration of this timestepper, the PDE is an
+        advection-diffusion equation with normalized advection of 0.5 and
+        normalized diffusion of 0.01.
+
+        **Arguments:**
+
+        - `num_spatial_dims`: The number of spatial dimensions `d`.
+        - `num_points`: The number of points `N` used to discretize the
+            domain. This **includes** the left boundary point and **excludes**
+            the right boundary point. In higher dimensions; the number of points
+            in each dimension is the same. Hence, the total number of degrees of
+            freedom is `Nᵈ`.
+        - `normalized_coefficients`: The coefficients of the normalized
+            dynamics. This must a tuple of floats. The length of the tuple
+            defines the highest occuring linear derivative in the PDE.
         """
         self.normalized_coefficients = normalized_coefficients
         super().__init__(
@@ -64,8 +92,41 @@ def __init__(
         difficulties: tuple[float, ...] = (0.0, -2.0),
     ):
         """
-        By default: Advection equation with CFL number 2 on 48 points resolution
-        in one spatial dimension.
+        Timestepper for d-dimensional (`d ∈ {1, 2, 3}`) linear PDEs on periodic
+        boundary conditions with normalized dynamics in a difficulty-based
+        interface.
+
+        Different to `NormalizedLinearStepper`, the dynamics are defined by
+        difficulties. The difficulties are a different combination of normalized
+        dynamics, `num_spatial_dims`, and `num_points`.
+
+            γᵢ = αᵢ Nⁱ 2ⁱ⁻¹ d
+
+        with `d` the number of spatial dimensions, `N` the number of points, and
+        `αᵢ` the normalized coefficient.
+
+        This interface is more natural because the difficulties for all orders
+        (given by `i`) are around 1.0. Additionally, they relate to stability
+        condition of explicit Finite Difference schemes for the particular
+        equations. For example, for advection (`i=1`), the absolute of the
+        difficulty is the Courant-Friedrichs-Lewy (CFL) number.
+
+        In the default configuration of this timestepper, the PDE is an
+        advection equation with CFL number 2 solved in 1d with 48 resolution
+        points to discretize the domain.
+
+        **Arguments:**
+
+        - `num_spatial_dims`: The number of spatial dimensions `d`. Default is
+            1.
+        - `num_points`: The number of points `N` used to discretize the domain.
+            This **includes** the left boundary point and **excludes** the right
+            boundary point. In higher dimensions; the number of points in each
+            dimension is the same. Hence, the total number of degrees of freedom
+            is `Nᵈ`. Default is 48.
+        - `difficulties`: The difficulties of the normalized dynamics. This must
+            be a tuple of floats. The length of the tuple defines the highest
+            occuring linear derivative in the PDE. Default is `(0.0, -2.0)`.
         """
         self.difficulties = difficulties
         normalized_coefficients = extract_normalized_coefficients_from_difficulty(
@@ -90,6 +151,24 @@ def __init__(
         difficulty: float = -2.0,
         order: int = 1,
     ):
+        """
+        A simple interface for `DifficultyLinearStepper` with only one
+        difficulty and a given order.
+
+        **Arguments:**
+
+        - `num_spatial_dims`: The number of spatial dimensions `d`. Default is
+            1.
+        - `num_points`: The number of points `N` used to discretize the domain.
+            This **includes** the left boundary point and **excludes** the right
+            boundary point. In higher dimensions; the number of points in each
+            dimension is the same. Hence, the total number of degrees of freedom
+            is `Nᵈ`. Default is 48.
+        - `difficulty`: The difficulty of the normalized dynamics. This must be
+            a float. Default is -2.0.
+        - `order`: The order of the derivative associated with the provided
+            difficulty. The default of 1 is the advection equation.
+        """
         difficulties = (0.0,) * (order) + (difficulty,)
         super().__init__(
             difficulties=difficulties,