Skip to content

Commit

Permalink
Docs tweak (#55)
Browse files Browse the repository at this point in the history 
* Change to proper markdown

* Add KS conservative docstring
  • Loading branch information
@Ceyron
Ceyron authored Oct 22, 2024
1 parent 5af02e8 commit 7b478f0
Show file tree
Hide file tree
Showing 2 changed files with 140 additions and 78 deletions.
63 changes: 61 additions & 2 deletions exponax/stepper/_kuramoto_sivashinsky.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
155 changes: 79 additions & 76 deletions exponax/stepper/generic/_linear.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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__(
Expand Down

0 comments on commit 7b478f0

Please sign in to comment.