From 7b478f07aede50bc5ec1ff5155da19bf8f967ef3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20K=C3=B6hler?= <27728103+Ceyron@users.noreply.github.com> Date: Tue, 22 Oct 2024 15:23:42 +0200 Subject: [PATCH] Docs tweak (#55) * Change to proper markdown * Add KS conservative docstring --- exponax/stepper/_kuramoto_sivashinsky.py | 63 ++++++++- exponax/stepper/generic/_linear.py | 155 ++++++++++++----------- 2 files changed, 140 insertions(+), 78 deletions(-) diff --git a/exponax/stepper/_kuramoto_sivashinsky.py b/exponax/stepper/_kuramoto_sivashinsky.py index fcc39ec..f37defa 100644 --- a/exponax/stepper/_kuramoto_sivashinsky.py +++ b/exponax/stepper/_kuramoto_sivashinsky.py @@ -195,8 +195,67 @@ def __init__( ): """ Using the fluid dynamics form of the KS equation (i.e. similar to the - Burgers equation). This also means that the number of channels grow with - the number of spatial dimensions. + Burgers equation). + + In 1d, the KS equation is given by + + ``` + uₜ + b₁ 1/2 (u²)ₓ + ψ₁ uₓₓ + ψ₂ uₓₓₓₓ = 0 + ``` + + with `b₁` the convection coefficient, `ψ₁` the second-order scale and + `ψ₂` the fourth-order. If the latter two terms were on the right-hand + side, they could be interpreted as diffusivity and hyper-diffusivity, + respectively. Here, the second-order term acts destabilizing (increases + the energy of the system) and the fourth-order term acts stabilizing + (decreases the energy of the system). A common configuration is `b₁ = ψ₁ + = ψ₂ = 1` and the dynamics are only adapted using the `domain_extent`. + For this, we espect the KS equation to experience spatio-temporal chaos + roughly once `L > 60`. + + !!! info + In this fluid dynamics (=conservative) format, the number of + channels grows with the spatial dimension. However, it seems that + this format does not generalize well to higher dimensions. For + higher dimensions, consider using the combustion format + (`exponax.stepper.KuramotoSivashinsky`) instead. + + **Arguments:** + + - `num_spatial_dims`: The number of spatial dimensions `d`. + - `domain_extent`: The size of the domain `L`; in higher dimensions + the domain is assumed to be a scaled hypercube `Ω = (0, L)ᵈ`. + - `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ᵈ`. + - `dt`: The timestep size `Δt` between two consecutive states. + - `convection_scale`: The convection coefficient `b₁`. Note that the + convection term is already scaled by 1/2. This factor allows for + further modification. Default: 1.0. + - `second_order_scale`: The "diffusivity" `ψ₁` in the KS equation. + - `fourth_order_diffusivity`: The "hyper-diffusivity" `ψ₂` in the KS + equation. + - `single_channel`: Whether to use a single channel for the spatial + dimension. Default: `False`. + - `conservative`: Whether to use the conservative format. Default: + `True`. + - `dealiasing_fraction`: The fraction of the wavenumbers to keep + before evaluating the nonlinearity. The default 2/3 corresponds to + Orszag's 2/3 rule. To fully eliminate aliasing, use 1/2. Default: + 2/3. + - `order`: The order of the Exponential Time Differencing Runge + Kutta method. Must be one of {0, 1, 2, 3, 4}. The option `0` only + solves the linear part of the equation. Use higher values for higher + accuracy and stability. The default choice of `2` is a good + compromise for single precision floats. + - `num_circle_points`: How many points to use in the complex contour + integral method to compute the coefficients of the exponential time + differencing Runge Kutta method. Default: 16. + - `circle_radius`: The radius of the contour used to compute the + coefficients of the exponential time differencing Runge Kutta + method. Default: 1.0. """ self.convection_scale = convection_scale self.second_order_scale = second_order_scale diff --git a/exponax/stepper/generic/_linear.py b/exponax/stepper/generic/_linear.py index 8a35dca..3860049 100644 --- a/exponax/stepper/generic/_linear.py +++ b/exponax/stepper/generic/_linear.py @@ -58,84 +58,87 @@ def __init__( 0`, `a_1 = -0.1`, and `a_2 = 0.01`. **Arguments:** - - `num_spatial_dims`: The number of spatial dimensions `d`. - - `domain_extent`: The size of the domain `L`; in higher dimensions - the domain is assumed to be a scaled hypercube `Ω = (0, L)ᵈ`. - - `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ᵈ`. - - `dt`: The timestep size `Δt` between two consecutive states. - - `linear_coefficients` (keyword-only): The list of coefficients `a_j` - corresponding to the derivatives. Default: `[0.0, -0.1, 0.01]`. + + - `num_spatial_dims`: The number of spatial dimensions `d`. + - `domain_extent`: The size of the domain `L`; in higher dimensions + the domain is assumed to be a scaled hypercube `Ω = (0, L)ᵈ`. + - `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ᵈ`. + - `dt`: The timestep size `Δt` between two consecutive states. + - `linear_coefficients` (keyword-only): The list of coefficients `a_j` + corresponding to the derivatives. Default: `[0.0, -0.1, 0.01]`. **Notes:** - - There is a repeating pattern in the effect of orders of - derivatives: - - Even derivatives (i.e., 0, 2, 4, 6, ...) scale the - solution. Order 0 scales all wavenumbers/modes equally (if - its coefficient is negative, this is also called a drag). - Order 2 scales higher wavenumbers/modes stronger with the - dependence on the effect on the wavenumber being - quadratically. Order 4 also scales but stronger than order - 4. Its dependency on the wavenumber is quartically. This - pattern continues for higher orders. - - Odd derivatives (i.e, 1, 3, 5, 7, ...) rotate the solution in - Fourier space. In state space, this is observed as - advection. Order 1 rotates all wavenumbers/modes equally. In - state space, this is observed in that the initial condition - just moves over the domain. Order 3 rotates higher - wavenumbers/modes stronger with the dependence on the - wavenumber being quadratic. If certain wavenumbers are - rotated at a different speed, there is still advection in - state space but certain patterns in the initial condition - are advected at different speeds. As such, it is observed - that the shape of the initial condition dissolves. The - effect continues for higher orders with the dependency on - the wavenumber becoming continuously stronger. - - Take care of the signs of coefficients. In contrast to the - indivial linear steppers ([`exponax.stepper.Advection`][], - [`exponax.stepper.Diffusion`][], etc.), the signs are not - automatically taken care of to produce meaningful coefficients. - For the general linear stepper all linear derivatives are on the - right-hand side of the equation. This has the following effect - based on the order of derivative (this a consequence of squaring - the imaginary unit returning -1): - - Zeroth-Order: A negative coeffcient is a drag and removes - energy from the system. A positive coefficient adds energy - to the system. - - First-Order: A negative coefficient rotates the solution - clockwise. A positive coefficient rotates the solution - counter-clockwise. Hence, negative coefficients advect - solutions to the right, positive coefficients advect - solutions to the left. - - Second-Order: A positive coefficient diffuses the solution - (i.e., removes energy from the system). A negative - coefficient adds energy to the system. - - Third-Order: A negative coefficient rotates the solution - counter-clockwise. A positive coefficient rotates the - solution clockwise. Hence, negative coefficients advect - solutions to the left, positive coefficients advect - solutions to the right. - - Fourth-Order: A negative coefficient diffuses the solution - (i.e., removes energy from the system). A positive - coefficient adds energy to the system. - - ... - - The stepper is unconditionally stable, no matter the choice of - any argument because the equation is solved analytically in - Fourier space. **However**, note if you have odd-order - derivative terms (e.g., advection or dispersion) and your - initial condition is **not** bandlimited (i.e., it contains - modes beyond the Nyquist frequency of `(N//2)+1`) there is a - chance spurious oscillations can occur. - - Ultimately, only the factors `a_j Δt / Lʲ` affect the - characteristic of the dynamics. See also - [`exponax.stepper.generic.NormalizedLinearStepper`][] with - `normalized_coefficients = [0, alpha_1, alpha_2, ...]` with - `alpha_j = coefficients[j] * dt / domain_extent**j`. You can use - the function [`exponax.stepper.generic.normalize_coefficients`][] to - obtain the normalized coefficients. + + - There is a repeating pattern in the effect of orders of + derivatives: + - Even derivatives (i.e., 0, 2, 4, 6, ...) scale the + solution. Order 0 scales all wavenumbers/modes equally (if + its coefficient is negative, this is also called a drag). + Order 2 scales higher wavenumbers/modes stronger with the + dependence on the effect on the wavenumber being + quadratically. Order 4 also scales but stronger than order + 4. Its dependency on the wavenumber is quartically. This + pattern continues for higher orders. + - Odd derivatives (i.e, 1, 3, 5, 7, ...) rotate the solution in + Fourier space. In state space, this is observed as + advection. Order 1 rotates all wavenumbers/modes equally. In + state space, this is observed in that the initial condition + just moves over the domain. Order 3 rotates higher + wavenumbers/modes stronger with the dependence on the + wavenumber being quadratic. If certain wavenumbers are + rotated at a different speed, there is still advection in + state space but certain patterns in the initial condition + are advected at different speeds. As such, it is observed + that the shape of the initial condition dissolves. The + effect continues for higher orders with the dependency on + the wavenumber becoming continuously stronger. + - Take care of the signs of coefficients. In contrast to the + indivial linear steppers ([`exponax.stepper.Advection`][], + [`exponax.stepper.Diffusion`][], etc.), the signs are not + automatically taken care of to produce meaningful coefficients. + For the general linear stepper all linear derivatives are on the + right-hand side of the equation. This has the following effect + based on the order of derivative (this a consequence of squaring + the imaginary unit returning -1): + - Zeroth-Order: A negative coeffcient is a drag and removes + energy from the system. A positive coefficient adds energy + to the system. + - First-Order: A negative coefficient rotates the solution + clockwise. A positive coefficient rotates the solution + counter-clockwise. Hence, negative coefficients advect + solutions to the right, positive coefficients advect + solutions to the left. + - Second-Order: A positive coefficient diffuses the solution + (i.e., removes energy from the system). A negative + coefficient adds energy to the system. + - Third-Order: A negative coefficient rotates the solution + counter-clockwise. A positive coefficient rotates the + solution clockwise. Hence, negative coefficients advect + solutions to the left, positive coefficients advect + solutions to the right. + - Fourth-Order: A negative coefficient diffuses the solution + (i.e., removes energy from the system). A positive + coefficient adds energy to the system. + - ... + - The stepper is unconditionally stable, no matter the choice of + any argument because the equation is solved analytically in + Fourier space. **However**, note if you have odd-order + derivative terms (e.g., advection or dispersion) and your + initial condition is **not** bandlimited (i.e., it contains + modes beyond the Nyquist frequency of `(N//2)+1`) there is a + chance spurious oscillations can occur. + - Ultimately, only the factors `a_j Δt / Lʲ` affect the + characteristic of the dynamics. See also + [`exponax.stepper.generic.NormalizedLinearStepper`][] with + `normalized_coefficients = [0, alpha_1, alpha_2, ...]` with + `alpha_j = coefficients[j] * dt / domain_extent**j`. You can use + the function + [`exponax.stepper.generic.normalize_coefficients`][] to obtain + the normalized coefficients. """ self.linear_coefficients = linear_coefficients super().__init__(