Expand Docs (#6)

* Move all resources into docs folder

* Embed design decisions

* Embed design decisions

* Intro to advection

* Add all linear time steppers

* Ensure documentation displays correctly

* Add nonlinear problems

* Ensure documentation displays properly

* Reformate for mkdocs

* Reformate for mkdocs

* Proxy setup of ICs to have reaction diffusion work

* Setup all reaction-diffusion steppers

* Comply with markdown

* Add docs for normalized and difficulty conversion utilties

* Add docs to general steppers

* Fix spelling mistake

* Adapt to name change

* Add all normalized steppers

* Add doc files for difficulty interface

* Add docs for all ICs

* Rework linking to make mkdocstrings work

* Add documentation for metrics

* Export placeholder functions

* Ensure consistent naming

* Add docs for visualization routines

* Add docs for smaller utility functions

* Add documentation for Poisson solver

* Add missing members selector

* Add ETDRK and base classes docs

* Add all documentation for the nonlinear functions

* Enhance landing page

README.md

@@ -1,6 +1,6 @@
 
 <h1 align="center">
-  <img src="img/exponax_logo.png" width="200">
+  <img src="docs/imgs/exponax_logo.png" width="200">
   <br>
     Exponax
   <br>
@@ -19,7 +19,7 @@
 </p>
 
 <p align="center">
-    <img src="img/teaser_demo.gif">
+    <img src="docs/imgs/teaser_demo.gif">
 </p>
 
 ## Installation
@@ -57,7 +57,7 @@ plt.imshow(trajectory[:, 0, :].T, aspect='auto', cmap='RdBu', vmin=-2, vmax=2, o
 plt.xlabel("Time"); plt.ylabel("Space"); plt.show()
 ```
 
-![](img/ks_rollout.png)
+![](docs/imgs/ks_rollout.png)
 
 For a next step, check out the [simple_advection_example_1d.ipynb](examples/simple_advection_example_1d.ipynb) notebook in the `examples` folder, and check out the <a href="#documentation">Documentation</a>.
 
@@ -95,7 +95,7 @@ For a next step, check out the [simple_advection_example_1d.ipynb](examples/simp
 
 The following Jupyter notebooks showcase the usage of the package:
 
-1. [Simple Advection Example in 1d](examples/simple_advection_example_1d.ipynb)
+1. [Simple Advection Example in 1d](docs/examples/simple_advection_example_1d.ipynb)
 2. ...
 
 The documentation is still in progress. For now, the best way to get started is

docs/api/etdrk_backbone.md

@@ -0,0 +1,55 @@
+# ETDRK Backbone
+
+Core clases that implement the Exponential Time Differencing Runge-Kutta (ETDRK)
+method for solving semi-linear PDEs in form of timesteppers. Require supplying
+the time step size $\Delta t$, the linear operator in Fourier space $\hat{\mathcal{L}}_h$, and the non-linear operator in Fourier space $\hat{\mathcal{N}}_h$.
+
+::: exponax.etdrk.ETDRK0
+    options:
+        members:
+            - __init__
+            - step_fourier
+
+---
+
+::: exponax.etdrk.ETDRK1
+    options:
+        members:
+            - __init__
+            - step_fourier
+
+---
+
+::: exponax.etdrk.ETDRK2
+    options:
+        members:
+            - __init__
+            - step_fourier
+
+---
+
+::: exponax.etdrk.ETDRK3
+    options:
+        members:
+            - __init__
+            - step_fourier
+
+---
+
+::: exponax.etdrk.ETDRK4
+    options:
+        members:
+            - __init__
+            - step_fourier
+
+---
+
+::: exponax.etdrk.BaseETDRK
+    options:
+        members:
+            - __init__
+            - step_fourier
+
+---
+
+::: exponax.etdrk.roots_of_unity

docs/api/stepper/difficulty/convection.md

@@ -0,0 +1,7 @@
+# Convection
+
+::: exponax.normalized.DifficultyConvectionStepper
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/difficulty/gradient_norm.md

@@ -0,0 +1,7 @@
+# Gradient Norm
+
+::: exponax.normalized.DifficultyGradientNormStepper  
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/difficulty/linear.md

@@ -0,0 +1,7 @@
+# Linear
+
+::: exponax.normalized.DifficultyLinearStepper  
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/difficulty/nonlinear.md

@@ -0,0 +1,7 @@
+# Nonlinear
+
+::: exponax.normalized.DifficultyGeneralNonlinearStepper
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/difficulty/polynomial.md

@@ -0,0 +1,7 @@
+# Polynomial
+
+::: exponax.normalized.DifficultyPolynomialStepper  
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/normalized/convection.md

@@ -0,0 +1,7 @@
+# Convection
+
+::: exponax.normalized.NormalizedConvectionStepper  
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/normalized/gradient_norm.md

@@ -0,0 +1,7 @@
+# Gradient NormA
+
+::: exponax.normalized.NormalizedGradientNormStepper  
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/normalized/nonlinear.md

@@ -0,0 +1,7 @@
+# Nonlinear
+
+::: exponax.normalized.NormalizedGeneralNonlinearStepper  
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/normalized/polynomial.md

@@ -0,0 +1,7 @@
+# Polynomial
+
+::: exponax.normalized.NormalizedPolynomialStepper  
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/normalized/vorticity_convection.md

@@ -0,0 +1,7 @@
+# Vorticity Convection
+
+::: exponax.normalized.NormalizedVorticityConvection  
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/burgers.md

@@ -0,0 +1,17 @@
+# Burgers
+
+In 1D:
+
+$$ \frac{\partial u}{\partial t} + \frac{1}{2} \frac{\partial u^2}{\partial x} = \nu \frac{\partial^2 u}{\partial x^2} $$
+
+In higher dimensions:
+
+$$ \frac{\partial u}{\partial t} + \frac{1}{2} \nabla \cdot (u \odot u) = \nu \nabla \cdot \nabla u $$
+
+(with as many channels (=velocity components) as spatial dimensions)
+
+::: exponax.stepper.Burgers
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/general/general_convection.md

@@ -0,0 +1,7 @@
+# General Convection Stepper
+
+::: exponax.stepper.GeneralConvectionStepper
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/general/general_gradient_norm.md

@@ -0,0 +1,7 @@
+# General Gradient Norm Stepper
+
+::: exponax.stepper.GeneralGradientNormStepper
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/general/general_linear.md

@@ -0,0 +1,7 @@
+# General Linear Stepper
+
+::: exponax.stepper.GeneralLinearStepper
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/general/general_nonlinear.md

@@ -0,0 +1,7 @@
+# General Nonlinear Stepper
+
+::: exponax.stepper.GeneralNonlinearStepper
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/general/general_polynomial.md

@@ -0,0 +1,7 @@
+# General Polynomial Stepper
+
+::: exponax.stepper.GeneralPolynomialStepper
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/general/general_vorticity_convection.md

@@ -0,0 +1,7 @@
+# General Vorticity Convection Stepper
+
+::: exponax.stepper.GeneralVorticityConvectionStepper
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/kdv.md

@@ -0,0 +1,7 @@
+# Korteweg-de Vries
+
+::: exponax.stepper.KortewegDeVries
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/ks.md

@@ -0,0 +1,17 @@
+# Kuramoto-Sivashinsky equation
+
+In 1D:
+
+$$ \frac{\partial u}{\partial t} + \frac{1}{2} \left(\frac{\partial u}{\partial x}\right)^2 + \frac{\partial^2 u}{\partial x^2} + \frac{\partial^4 u}{\partial x^4} = 0 $$
+
+In higher dimensions:
+
+$$ \frac{\partial u}{\partial t} + \frac{1}{2} \left \| \nabla u \right \|^2 + \nabla \cdot \nabla u + \nabla \cdot (\nabla \odot \nabla \odot \nabla) u = 0 $$
+
+Uses the combustion format via the gradient norm that easily scales to higher dimensions.
+
+::: exponax.stepper.KuramotoSivashinsky
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/ks_cons.md

@@ -0,0 +1,11 @@
+# Kuramoto-Sivashinsky (conservative format)
+
+Uses the convection nonlinearity similar to Burgers, but only works in 1D:
+
+$$ \frac{\partial u}{\partial t} + \frac{1}{2} \frac{\partial u^2}{\partial x} + \frac{\partial^2 u}{\partial x^2} + \frac{\partial^4 u}{\partial x^4} = 0 $$
+
+::: exponax.stepper.KuramotoSivashinskyConservative
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/linear/advection.md

@@ -1,7 +1,14 @@
 # Advection
 
+In 1D:
+
 $$ \frac{\partial u}{\partial t} + c \frac{\partial u}{\partial x} = 0 $$
 
+In higher dimensions:
+
+$$ \frac{\partial u}{\partial t} + \vec{c} \cdot \nabla u = 0 $$
+
+(often just $\vec{c} = c \vec{1}$)
 
 
 ::: exponax.stepper.Advection

docs/api/stepper/physical/linear/advection_diffusion.md

@@ -0,0 +1,17 @@
+# Advection-Diffusion
+
+In 1D:
+
+$$ \frac{\partial u}{\partial t} + c \frac{\partial u}{\partial x} = \nu \frac{\partial^2 u}{\partial x^2} $$
+
+In higher dimensions:
+
+$$ \frac{\partial u}{\partial t} + \vec{c} \cdot \nabla u = \nu \nabla \cdot \nabla u $$
+
+(often just $\vec{c} = c \vec{1}$) and potentially with anisotropic diffusion.
+
+::: exponax.stepper.AdvectionDiffusion
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/linear/diffusion.md

@@ -0,0 +1,21 @@
+# Diffusion
+
+In 1D:
+
+$$ \frac{\partial u}{\partial t} = \nu \frac{\partial^2 u}{\partial x^2} $$
+
+In higher dimensions:
+
+$$ \frac{\partial u}{\partial t} = \nu \nabla \cdot \nabla u $$
+
+or with anisotropic diffusion:
+
+$$ \frac{\partial u}{\partial t} = \nabla \cdot \left( A \nabla u \right) $$
+
+with $A \in \R^{D \times D}$ symmetric positive definite.
+
+::: exponax.stepper.Diffusion
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/linear/dispersion.md

@@ -0,0 +1,19 @@
+# Dispersion
+
+In 1D:
+
+$$ \frac{\partial u}{\partial t} = \xi \frac{\partial^3 u}{\partial x^3} $$
+
+In higher dimensions:
+
+$$ \frac{\partial u}{\partial t} = \xi \nabla \cdot (\nabla \odot \nabla) u $$
+
+or with spatial mixing:
+
+$$ \frac{\partial u}{\partial t} = \xi (1 \cdot \nabla) (\nabla \cdot \nabla) u $$
+
+::: exponax.stepper.Dispersion
+    options:
+        members:
+            - __init__
+            - __call__

docs/api/stepper/physical/linear/hyper_diffusion.md

@@ -0,0 +1,19 @@
+# Hyper-Diffusion
+
+In 1D:
+
+$$ \frac{\partial u}{\partial t} = \xi \frac{\partial^4 u}{\partial x^4} $$
+
+In higher dimensions:
+
+$$ \frac{\partial u}{\partial t} = \zeta \nabla \cdot (\nabla \odot \nabla \odot \nabla) u $$
+
+or with spatial mixing:
+
+$$ \frac{\partial u}{\partial t} = \zeta (\nabla \cdot \nabla)(\nabla \cdot \nabla) u $$
+
+::: exponax.stepper.HyperDiffusion
+    options:
+        members:
+            - __init__
+            - __call__