Stepper restructure (#21)

* Move reaction into stepper * Adapt imports in tests * Move linear timesteppers into separete files * Move generic physical stepper into submodule * Rename to nonlinear * Correctly export in submodule * Move utilities * Export generic utilities * Fully translate linear generic stepper * Fully translate convection stepper * Fully translate generic nonlinear stepper * Fully translate generic Gradient norm stepper * Correctly forward dealiasing fraction * No need to set dealiasing fraction * Fully translate generic polynomial stepper * Don't translate vorticity convection * Remove normalized submodule * Remove no longer relevant exports * Export generic stepper * Fix issues with dealiasing_fraction arguments * Adapt tests * Remove commented sections * Adapt cross-references * New docs layout to better reflect the API * Add a boilerplate for the overview
Ceyron · Sep 2, 2024 · 9ea7788 · 9ea7788
1 parent 545fd3f
commit 9ea7788
Show file tree

Hide file tree

Showing 66 changed files with 1,452 additions and 1,618 deletions.
diff --git a/docs/api/stepper/physical/poisson.md → docs/api/stepper/additional/poisson.md b/docs/api/stepper/physical/poisson.md → docs/api/stepper/additional/poisson.md
diff --git a/docs/api/stepper/difficulty/convection.md → ...neric/difficulty/difficulty_convection.md b/docs/api/stepper/difficulty/convection.md → ...neric/difficulty/difficulty_convection.md
@@ -1,6 +1,6 @@
 # Convection
 
-::: exponax.normalized.DifficultyConvectionStepper
+::: exponax.stepper.generic.DifficultyConvectionStepper
     options:
         members:
             - __init__

diff --git a/docs/api/stepper/difficulty/gradient_norm.md → ...ic/difficulty/difficulty_gradient_norm.md b/docs/api/stepper/difficulty/gradient_norm.md → ...ic/difficulty/difficulty_gradient_norm.md
@@ -1,6 +1,6 @@
 # Gradient Norm
 
-::: exponax.normalized.DifficultyGradientNormStepper  
+::: exponax.stepper.generic.DifficultyGradientNormStepper  
     options:
         members:
             - __init__

diff --git a/docs/api/stepper/difficulty/linear.md → ...r/generic/difficulty/difficulty_linear.md b/docs/api/stepper/difficulty/linear.md → ...r/generic/difficulty/difficulty_linear.md
@@ -1,6 +1,6 @@
 # Linear
 
-::: exponax.normalized.DifficultyLinearStepper  
+::: exponax.stepper.generic.DifficultyLinearStepper  
     options:
         members:
             - __init__

diff --git a/docs/api/stepper/difficulty/nonlinear.md → ...eneric/difficulty/difficulty_nonlinear.md b/docs/api/stepper/difficulty/nonlinear.md → ...eneric/difficulty/difficulty_nonlinear.md
@@ -1,6 +1,6 @@
 # Nonlinear
 
-::: exponax.normalized.DifficultyGeneralNonlinearStepper
+::: exponax.stepper.generic.DifficultyNonlinearStepper
     options:
         members:
             - __init__

diff --git a/docs/api/stepper/difficulty/polynomial.md → ...neric/difficulty/difficulty_polynomial.md b/docs/api/stepper/difficulty/polynomial.md → ...neric/difficulty/difficulty_polynomial.md
@@ -1,6 +1,6 @@
 # Polynomial
 
-::: exponax.normalized.DifficultyPolynomialStepper  
+::: exponax.stepper.generic.DifficultyPolynomialStepper  
     options:
         members:
             - __init__

diff --git a/docs/api/stepper/normalized/convection.md → ...neric/normalized/normalized_convection.md b/docs/api/stepper/normalized/convection.md → ...neric/normalized/normalized_convection.md
@@ -1,6 +1,6 @@
 # Convection
 
-::: exponax.normalized.NormalizedConvectionStepper  
+::: exponax.stepper.generic.NormalizedConvectionStepper  
     options:
         members:
             - __init__

diff --git a/docs/api/stepper/normalized/gradient_norm.md → ...ic/normalized/normalized_gradient_norm.md b/docs/api/stepper/normalized/gradient_norm.md → ...ic/normalized/normalized_gradient_norm.md
@@ -1,6 +1,6 @@
 # Gradient NormA
 
-::: exponax.normalized.NormalizedGradientNormStepper  
+::: exponax.stepper.generic.NormalizedGradientNormStepper  
     options:
         members:
             - __init__

diff --git a/docs/api/stepper/normalized/linear.md → ...r/generic/normalized/normalized_linear.md b/docs/api/stepper/normalized/linear.md → ...r/generic/normalized/normalized_linear.md
@@ -1,5 +1,5 @@
 
-::: exponax.normalized.NormalizedLinearStepper
+::: exponax.stepper.generic.NormalizedLinearStepper
     options:
         members:
             - __init__

diff --git a/docs/api/stepper/normalized/nonlinear.md → ...eneric/normalized/normalized_nonlinear.md b/docs/api/stepper/normalized/nonlinear.md → ...eneric/normalized/normalized_nonlinear.md
@@ -1,6 +1,6 @@
 # Nonlinear
 
-::: exponax.normalized.NormalizedGeneralNonlinearStepper  
+::: exponax.stepper.generic.NormalizedNonlinearStepper  
     options:
         members:
             - __init__

diff --git a/docs/api/stepper/normalized/polynomial.md → ...neric/normalized/normalized_polynomial.md b/docs/api/stepper/normalized/polynomial.md → ...neric/normalized/normalized_polynomial.md
@@ -1,6 +1,6 @@
 # Polynomial
 
-::: exponax.normalized.NormalizedPolynomialStepper  
+::: exponax.stepper.generic.NormalizedPolynomialStepper  
     options:
         members:
             - __init__

diff --git a/...er/physical/general/general_convection.md → ...er/generic/physical/general_convection.md b/...er/physical/general/general_convection.md → ...er/generic/physical/general_convection.md
@@ -1,6 +1,6 @@
 # General Convection Stepper
 
-::: exponax.stepper.GeneralConvectionStepper
+::: exponax.stepper.generic.GeneralConvectionStepper
     options:
         members:
             - __init__

diff --git a/...physical/general/general_gradient_norm.md → ...generic/physical/general_gradient_norm.md b/...physical/general/general_gradient_norm.md → ...generic/physical/general_gradient_norm.md
@@ -1,6 +1,6 @@
 # General Gradient Norm Stepper
 
-::: exponax.stepper.GeneralGradientNormStepper
+::: exponax.stepper.generic.GeneralGradientNormStepper
     options:
         members:
             - __init__

diff --git a/...tepper/physical/general/general_linear.md → ...tepper/generic/physical/general_linear.md b/...tepper/physical/general/general_linear.md → ...tepper/generic/physical/general_linear.md
@@ -1,6 +1,6 @@
 # General Linear Stepper
 
-::: exponax.stepper.GeneralLinearStepper
+::: exponax.stepper.generic.GeneralLinearStepper
     options:
         members:
             - __init__

diff --git a/...per/physical/general/general_nonlinear.md → ...per/generic/physical/general_nonlinear.md b/...per/physical/general/general_nonlinear.md → ...per/generic/physical/general_nonlinear.md
@@ -1,6 +1,6 @@
 # General Nonlinear Stepper
 
-::: exponax.stepper.GeneralNonlinearStepper
+::: exponax.stepper.generic.GeneralNonlinearStepper
     options:
         members:
             - __init__

diff --git a/...er/physical/general/general_polynomial.md → ...er/generic/physical/general_polynomial.md b/...er/physical/general/general_polynomial.md → ...er/generic/physical/general_polynomial.md
@@ -1,6 +1,6 @@
 # General Polynomial Stepper
 
-::: exponax.stepper.GeneralPolynomialStepper
+::: exponax.stepper.generic.GeneralPolynomialStepper
     options:
         members:
             - __init__

diff --git a/...l/general/general_vorticity_convection.md → .../physical/general_vorticity_convection.md b/...l/general/general_vorticity_convection.md → .../physical/general_vorticity_convection.md
@@ -1,6 +1,6 @@
 # General Vorticity Convection Stepper
 
-::: exponax.stepper.GeneralVorticityConvectionStepper
+::: exponax.stepper.generic.GeneralVorticityConvectionStepper
     options:
         members:
             - __init__

diff --git a/.../api/stepper/physical/linear/advection.md → docs/api/stepper/linear/advection.md b/.../api/stepper/physical/linear/advection.md → docs/api/stepper/linear/advection.md
diff --git a/...er/physical/linear/advection_diffusion.md → ...api/stepper/linear/advection_diffusion.md b/...er/physical/linear/advection_diffusion.md → ...api/stepper/linear/advection_diffusion.md
diff --git a/.../api/stepper/physical/linear/diffusion.md → docs/api/stepper/linear/diffusion.md b/.../api/stepper/physical/linear/diffusion.md → docs/api/stepper/linear/diffusion.md
diff --git a/...api/stepper/physical/linear/dispersion.md → docs/api/stepper/linear/dispersion.md b/...api/stepper/physical/linear/dispersion.md → docs/api/stepper/linear/dispersion.md
diff --git a/...tepper/physical/linear/hyper_diffusion.md → docs/api/stepper/linear/hyper_diffusion.md b/...tepper/physical/linear/hyper_diffusion.md → docs/api/stepper/linear/hyper_diffusion.md
diff --git a/docs/api/stepper/physical/burgers.md → docs/api/stepper/nonlinear/burgers.md b/docs/api/stepper/physical/burgers.md → docs/api/stepper/nonlinear/burgers.md
diff --git a/docs/api/stepper/physical/kdv.md → docs/api/stepper/nonlinear/kdv.md b/docs/api/stepper/physical/kdv.md → docs/api/stepper/nonlinear/kdv.md
diff --git a/docs/api/stepper/physical/ks.md → docs/api/stepper/nonlinear/ks.md b/docs/api/stepper/physical/ks.md → docs/api/stepper/nonlinear/ks.md
diff --git a/docs/api/stepper/physical/ks_cons.md → docs/api/stepper/nonlinear/ks_cons.md b/docs/api/stepper/physical/ks_cons.md → docs/api/stepper/nonlinear/ks_cons.md
diff --git a/docs/api/stepper/physical/navier_stokes.md → docs/api/stepper/nonlinear/navier_stokes.md b/docs/api/stepper/physical/navier_stokes.md → docs/api/stepper/nonlinear/navier_stokes.md
diff --git a/docs/api/stepper/normalized/vorticity_convection.md b/docs/api/stepper/normalized/vorticity_convection.md
diff --git a/docs/api/stepper/overview.md b/docs/api/stepper/overview.md
@@ -0,0 +1,23 @@
+# Overview
+
+`Exponax` comes with many pre-built dynamics. They are all based on the idea of
+solving semi-linear PDEs
+
+$$
+\partial_t u = \mathcal{L} u + \mathcal{N}(u)
+$$
+
+where $\mathcal{L}$ is a linear operator and $\mathcal{N}$ is a non-linear
+differential operator.
+
+TODO: add classification of dynamics based on:
+
+- linear or nonlinear or reaction-diffusion
+- specific (i.e. concrete equations like advection, Burgers etc.) or generic
+  based on providing a collection of linear and nonlinear coefficients
+- if generic: whether it uses a physical, normalized or difficulty-based
+  interface
+- in higher dimensions: whether it behaves isotropic or anisotropic (with
+  different coefficients per direction)
+
+Then the resulting behavior can also be classified into ...
diff --git a/...physical/reaction_diffusion/allen_cahn.md → docs/api/stepper/reaction/allen_cahn.md b/...physical/reaction_diffusion/allen_cahn.md → docs/api/stepper/reaction/allen_cahn.md
@@ -1,6 +1,6 @@
 # Allen-Cahn
 
-::: exponax.reaction.AllenCahn
+::: exponax.stepper.reaction.AllenCahn
     options:
         members:
             - __init__

diff --git a/...sical/reaction_diffusion/cahn_hilliard.md → docs/api/stepper/reaction/cahn_hilliard.md b/...sical/reaction_diffusion/cahn_hilliard.md → docs/api/stepper/reaction/cahn_hilliard.md
@@ -1,6 +1,6 @@
 # Cahn-Hilliad
 
-::: exponax.reaction.CahnHilliard
+::: exponax.stepper.reaction.CahnHilliard
     options:
         members:
             - __init__

diff --git a/...physical/reaction_diffusion/fisher_kpp.md → docs/api/stepper/reaction/fisher_kpp.md b/...physical/reaction_diffusion/fisher_kpp.md → docs/api/stepper/reaction/fisher_kpp.md
@@ -1,6 +1,6 @@
 # Fisher-KPP
 
-::: exponax.reaction.FisherKPP
+::: exponax.stepper.reaction.FisherKPP
     options:
         members:
             - __init__

diff --git a/...physical/reaction_diffusion/gray_scott.md → docs/api/stepper/reaction/gray_scott.md b/...physical/reaction_diffusion/gray_scott.md → docs/api/stepper/reaction/gray_scott.md
@@ -1,6 +1,6 @@
 # Gray-Scott
 
-::: exponax.reaction.GrayScott
+::: exponax.stepper.reaction.GrayScott
     options:
         members:
             - __init__

diff --git a/...cal/reaction_diffusion/swift_hohenberg.md → docs/api/stepper/reaction/swift_hohenberg.md b/...cal/reaction_diffusion/swift_hohenberg.md → docs/api/stepper/reaction/swift_hohenberg.md
@@ -1,6 +1,6 @@
 # Swift-Hohenberg
 
-::: exponax.reaction.SwiftHohenberg
+::: exponax.stepper.reaction.SwiftHohenberg
     options:
         members:
             - __init__

diff --git a/docs/api/utilities/normalized_and_difficulty.md b/docs/api/utilities/normalized_and_difficulty.md
@@ -1,63 +1,63 @@
 # Conversion Utilties for Normalized and Difficulty Steppers
 
-:::exponax.normalized.normalize_coefficients
+:::exponax.stepper.generic.normalize_coefficients
 
 ---
 
-:::exponax.normalized.denormalize_coefficients
+:::exponax.stepper.generic.denormalize_coefficients
 
 ---
 
-:::exponax.normalized.normalize_convection_scale
+:::exponax.stepper.generic.normalize_convection_scale
 
 ---
 
-:::exponax.normalized.denormalize_convection_scale
+:::exponax.stepper.generic.denormalize_convection_scale
 
 ---
 
-:::exponax.normalized.normalize_gradient_norm_scale
+:::exponax.stepper.generic.normalize_gradient_norm_scale
 
 ---
 
-:::exponax.normalized.denormalize_gradient_norm_scale
+:::exponax.stepper.generic.denormalize_gradient_norm_scale
 
 ---
 
-:::exponax.normalized.normalize_polynomial_scales
+:::exponax.stepper.generic.normalize_polynomial_scales
 
 ---
 
-:::exponax.normalized.denormalize_polynomial_scales
+:::exponax.stepper.generic.denormalize_polynomial_scales
 
 ---
 
-:::exponax.normalized.reduce_normalized_coefficients_to_difficulty
+:::exponax.stepper.generic.reduce_normalized_coefficients_to_difficulty
 
 ---
 
-:::exponax.normalized.extract_normalized_coefficients_from_difficulty
+:::exponax.stepper.generic.extract_normalized_coefficients_from_difficulty
 
 ---
 
-:::exponax.normalized.reduce_normalized_convection_scale_to_difficulty
+:::exponax.stepper.generic.reduce_normalized_convection_scale_to_difficulty
 
 ---
 
-:::exponax.normalized.extract_normalized_convection_scale_from_difficulty
+:::exponax.stepper.generic.extract_normalized_convection_scale_from_difficulty
 
 ---
 
-:::exponax.normalized.reduce_normalized_gradient_norm_scale_to_difficulty
+:::exponax.stepper.generic.reduce_normalized_gradient_norm_scale_to_difficulty
 
 ---
 
-:::exponax.normalized.extract_normalized_gradient_norm_scale_from_difficulty
+:::exponax.stepper.generic.extract_normalized_gradient_norm_scale_from_difficulty
 
 <!-- ---
 
-:::exponax.normalized.reduce_normalized_nonlinear_scales_to_difficulty
+:::exponax.stepper.generic.reduce_normalized_nonlinear_scales_to_difficulty
 
 ---
 
-:::exponax.normalized.extract_normalized_nonlinear_scales_from_difficulty -->
+:::exponax.stepper.generic.extract_normalized_nonlinear_scales_from_difficulty -->
diff --git a/exponax/__init__.py b/exponax/__init__.py
@@ -1,7 +1,7 @@
 from . import _metrics as metrics
 from . import _poisson as poisson
 from . import _spectral as spectral
-from . import etdrk, ic, nonlin_fun, normalized, reaction, stepper, viz
+from . import etdrk, ic, nonlin_fun, stepper, viz
 from ._base_stepper import BaseStepper
 from ._forced_stepper import ForcedStepper
 from ._repeated_stepper import RepeatedStepper
@@ -36,8 +36,6 @@
     "etdrk",
     "ic",
     "nonlin_fun",
-    "normalized",
-    "reaction",
     "stepper",
     "viz",
     "spectral",