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__(