The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see [1]), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see [2]). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.25 on Wednesday 13 September 2023. Using Julia version 1.9.3.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
Family of IMEX SSPRK algorithms parametrized by the value β from [12], Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in [11].
An IMEX ARK algorithm from [15] with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore
include("report_gen.jl")
┌ Warning: Order uncertainty too large for RK4 (ark_analytic)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
+┌ Warning: Order uncertainty too large for RK4 (ark_onewaycouple_mri)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
L. J. Wicker and W. C. Skamarock. A time-splitting scheme for the elastic equations incorporating second-order Runge–Kutta time differencing. Monthly Weather Review 126, 1992–1999 (1998).
D. J. Gardner, J. E. Guerra, F. P. Hamon, D. R. Reynolds, P. A. Ullrich and Woodward. Implicit–explicit (IMEX) Runge–Kutta methods for non-hydrostatic atmospheric models. Geoscientific Model Development 11, 1497–1515 (2018).
+
[12]
+
+
S. Conde, S. Gottlieb, Z. J. Grant and J. N. Shadid. Implicit and Implicit–Explicit Strong Stability Preserving Runge–Kutta Methods with High Linear Order. Journal of Scientific Computing 73, 667–-690 (2017).
This document was generated with Documenter.jl version 0.27.25 on Wednesday 13 September 2023. Using Julia version 1.9.3.
diff --git a/dev/search_index.js b/dev/search_index.js
new file mode 100644
index 000000000..7a51098d4
--- /dev/null
+++ b/dev/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see [1]), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see [2]). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"[3] defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods ([4], [5])","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"[6] and [7] define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"rapplypatch.jl\")) # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from [8], section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from [8], section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from [8], section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from [8], section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from [8], section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from [9], Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from [9], Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from [9], Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from [9], Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from [9], Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from [9], Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from [9], Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from [9], Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from [10], with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in [11].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from [10], with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from [10], with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in [11].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from [12], Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in [11].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from [10], with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in [11].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from [13], Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from [14], section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from [15] with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from [16], Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from [16], Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher\nRK4","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from [17], with 2 stages and 2nd order accuracy. Also called Heun's method ([18]).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from [17], with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.RK4","page":"ODE Solvers","title":"ClimaTimeSteppers.RK4","text":"RK4\n\nThe RK4 algorithm from [19], a Runge-Kutta method with 4 stages and 4th order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of [20].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of [21] with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of [4] and [5].\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in [6] and [7], which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of [6].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of [7].\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from SciMLBase.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/dev/siteinfo.js b/dev/siteinfo.js
new file mode 100644
index 000000000..334349194
--- /dev/null
+++ b/dev/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "dev";
diff --git a/dev/test_problems/diffusion_2d/index.html b/dev/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..d7126ec2c
--- /dev/null
+++ b/dev/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.23 on Wednesday 4 January 2023. Using Julia version 1.8.4.
ClimaTimeSteppers.jl supports several time stepping schemes, and this Venn Diagram illustrates the classification of certain algorithms (and properties) of interest.
Settings
This document was generated with Documenter.jl version 0.27.23 on Wednesday 4 January 2023. Using Julia version 1.8.4.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
A generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.
Generates an IMEXARKTableau struct from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractTableau)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
+
+
Settings
This document was generated with Documenter.jl version 0.27.23 on Wednesday 4 January 2023. Using Julia version 1.8.4.
This document was generated with Documenter.jl version 0.27.23 on Wednesday 4 January 2023. Using Julia version 1.8.4.
diff --git a/previews/PR104/search_index.js b/previews/PR104/search_index.js
new file mode 100644
index 000000000..2524e6b7f
--- /dev/null
+++ b/previews/PR104/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"algo_formulations/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"api/nl_solvers/#Newton's-Method","page":"Non-linear solvers","title":"Newton's Method","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"NewtonsMethod","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewtonsMethod","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Newton-Krylov-Method","page":"Non-linear solvers","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.KrylovMethod","page":"Non-linear solvers","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForcingTerm","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ConstantForcing","page":"Non-linear solvers","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Non-linear solvers","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Non-linear solvers","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.PrintConditionNumber","page":"Non-linear solvers","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Jacobian-free-Newton-Krylov-Method","page":"Non-linear solvers","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.JacobianFreeJVP","page":"Non-linear solvers","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffJVP","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Convergence-Conditions","page":"Non-linear solvers","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ConvergenceChecker","page":"Non-linear solvers","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ConvergenceCondition","page":"Non-linear solvers","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MaximumError","page":"Non-linear solvers","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MaximumRelativeError","page":"Non-linear solvers","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MaximumErrorReduction","page":"Non-linear solvers","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Non-linear solvers","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MultipleConditions","page":"Non-linear solvers","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Update-Signals","page":"Non-linear solvers","title":"Update Signals","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateSignalHandler","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateEvery","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateEveryN","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateEveryDt","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateSignal","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewTimeStep","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewNewtonSolve","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewNewtonIteration","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algo_formulations/#Algorithm-formulations","page":"Algorithm formulations","title":"Algorithm formulations","text":"","category":"section"},{"location":"algo_formulations/","page":"Algorithm formulations","title":"Algorithm formulations","text":"ClimaTimeSteppers.jl supports several time stepping schemes, and this Venn Diagram illustrates the classification of certain algorithms (and properties) of interest.","category":"page"},{"location":"algo_formulations/","page":"Algorithm formulations","title":"Algorithm formulations","text":"(Image: )","category":"page"},{"location":"algo_formulations/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"algo_formulations/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"algo_formulations/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"algo_formulations/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"algo_formulations/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"dev/report_gen/#Report-generator","page":"Report generator","title":"Report generator","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In this section, we create a report comparing the solution errors and convergence orders for several test problems and algorithms.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots for ark_analytic: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots for ark_analytic_nonlin: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots for ark_analytic_sys: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)","category":"page"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractTableau)","category":"page"},{"location":"algo_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"algo_formulations/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algo_formulations/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algo_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algo_formulations/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"nl_solvers/formulation/#Non-linear-solvers-formulation","page":"Formulation","title":"Non-linear solvers formulation","text":"","category":"section"},{"location":"nl_solvers/formulation/#Newton's-method","page":"Formulation","title":"Newton's method","text":"","category":"section"},{"location":"nl_solvers/formulation/","page":"Formulation","title":"Formulation","text":"TODO: fill out","category":"page"},{"location":"api/algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/algorithms/#Interface-and-OrdinaryDiffEq-compatibility","page":"Algorithms","title":"Interface and OrdinaryDiffEq compatibility","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"ForwardEulerODEFunction","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"Algorithms","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#IMEX-ARK-methods","page":"Algorithms","title":"IMEX ARK methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"IMEXARKAlgorithm\nIMEXARKTableau","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.IMEXARKAlgorithm","page":"Algorithms","title":"ClimaTimeSteppers.IMEXARKAlgorithm","text":"IMEXARKAlgorithm(\n tabname::AbstractTableau,\n newtons_method\n) <: DistributedODEAlgorithm\n\nA generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.IMEXARKTableau","page":"Algorithms","title":"ClimaTimeSteppers.IMEXARKTableau","text":"IMEXARKTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nGenerates an IMEXARKTableau struct from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ARS","page":"Algorithms","title":"ARS","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"ARS111\nARS121\nARS232\nARS343","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS111","page":"Algorithms","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nThe Forward-Backward (1,1,1) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.1.\n\nThis is equivalent to the OrdinaryDiffEq.IMEXEuler algorithm.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS121","page":"Algorithms","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nThe Forward-Backward (1,2,1) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.2.\n\nThis is equivalent to the OrdinaryDiffEq.IMEXEulerARK algorithm.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS232","page":"Algorithms","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nThe Forward-Backward (2,3,2) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.5.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS343","page":"Algorithms","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nThe L-stable, third-order (3,4,3) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.7.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR104/siteinfo.js b/previews/PR104/siteinfo.js
new file mode 100644
index 000000000..f5c1f44e3
--- /dev/null
+++ b/previews/PR104/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR104";
diff --git a/previews/PR104/test_problems/index.html b/previews/PR104/test_problems/index.html
new file mode 100644
index 000000000..9648df4bd
--- /dev/null
+++ b/previews/PR104/test_problems/index.html
@@ -0,0 +1,2 @@
+
+Test problems · ClimaTimeSteppers
The second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Heun's method.) Exact choice of coefficients from wikipedia page for Heun's method :)
References
@article{shu1988efficient,
+ title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},
+ author={Shu, Chi-Wang and Osher, Stanley},
+ journal={Journal of computational physics},
+ volume={77},
+ number={2},
+ pages={439--471},
+ year={1988},
+ publisher={Elsevier}
+}
+@article {Heun1900,
+ title = {Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabh"{a}ngigen Ver"{a}nderlichen}
+ author = {Heun, Karl},
+ journal = {Z. Math. Phys},
+ volume = {45},
+ pages = {23--38},
+ year = {1900}
+}
The second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Ralstons's method.) Exact choice of coefficients from wikipedia page for Heun's method :)
The third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Spiteri and Ruuth (1988)
References
@article{spiteri2002new,
+ title={A new class of optimal high-order strong-stability-preserving time discretization methods},
+ author={Spiteri, Raymond J and Ruuth, Steven J},
+ journal={SIAM Journal on Numerical Analysis},
+ volume={40},
+ number={2},
+ pages={469--491},
+ year={2002},
+ publisher={SIAM}
+}
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of Giraldo, Kelly and Constantinescu (2013).
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
References
Giraldo, F.X.; Kelly, J.F. and Constantinescu, E.M. (2013) "Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA)", SIAM Journal on Scientific Computing, 35(5): B1162–B1194 doi: 10.1137/120876034
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl on Tuesday 28 July 2020. Using Julia version 1.4.2.
Schlegel, M., Knoth, O., Arnold, M., and Wolke, R. (2012) "Implementation of multirate time integration methods for air pollution modelling", Geosci. Model Dev., 5, 1395–1405, doi: 10.5194/gmd-5-1395-2012
Settings
This document was generated with Documenter.jl on Tuesday 28 July 2020. Using Julia version 1.4.2.
TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
This document was generated with Documenter.jl on Tuesday 28 July 2020. Using Julia version 1.4.2.
diff --git a/previews/PR11/search_index.js b/previews/PR11/search_index.js
new file mode 100644
index 000000000..2c881f1db
--- /dev/null
+++ b/previews/PR11/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"background/MultirateRungeKutta/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau \n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/MultirateRungeKutta/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau \n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/MultirateRungeKutta/#References","page":"Multirate Runge Kutta","title":"References","text":"","category":"section"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Schlegel, M., Knoth, O., Arnold, M., and Wolke, R. (2012) \"Implementation of multirate time integration methods for air pollution modelling\", Geosci. Model Dev., 5, 1395–1405, doi: 10.5194/gmd-5-1395-2012","category":"page"},{"location":"background/LowStorageRungeKutta/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/AdditiveRungeKutta/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/AdditiveRungeKutta/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/AdditiveRungeKutta/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"background/StrongStabilityPreservingRungeKutta/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/StrongStabilityPreservingRungeKutta/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/StrongStabilityPreservingRungeKutta/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/StrongStabilityPreservingRungeKutta/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/StrongStabilityPreservingRungeKutta/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"#TimeMachine.jl","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"","category":"section"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#TimeMachine.LSRK54CarpenterKennedy","page":"Algorithms","title":"TimeMachine.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe fourth-order, 5-stage low storage Runge–Kutta scheme from Carpenter and Kennedy (1994). The coefficients are those from Solution 3 in the paper.\n\nReferences\n\nCarpenter, M.H.; Kennedy, C.A. (1994) \"Fourth-order 2N-storage Runge–Kutta schemes\", NASA Technical Memorandum 109112. http://hdl.handle.net/2060/19940028444\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"TimeMachine.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe fourth-order, 14-stage, low-storage, Runge–Kutta scheme of Niegemann, Diehl, and Busch (2012) with optimized stability region\n\nReferences\n\nNiegemann, J.; Diehl, R.; Busch, K. (2012) \"Efficient low-storage Runge–Kutta schemes with optimized stability regions\", Journal of Computational Physics 231(2): 364–372. doi: 10.1016/j.jcp.2011.09.003\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRKEulerMethod","page":"Algorithms","title":"TimeMachine.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"SSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#TimeMachine.SSPRK22Heuns","page":"Algorithms","title":"TimeMachine.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Heun's method.) Exact choice of coefficients from wikipedia page for Heun's method :)\n\nReferences\n\n@article{shu1988efficient,\n title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},\n author={Shu, Chi-Wang and Osher, Stanley},\n journal={Journal of computational physics},\n volume={77},\n number={2},\n pages={439--471},\n year={1988},\n publisher={Elsevier}\n}\n@article {Heun1900,\n title = {Neue Methoden zur approximativen Integration der\n Differentialgleichungen einer unabh\"{a}ngigen Ver\"{a}nderlichen}\n author = {Heun, Karl},\n journal = {Z. Math. Phys},\n volume = {45},\n pages = {23--38},\n year = {1900}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Ralstons","page":"Algorithms","title":"TimeMachine.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Ralstons's method.) Exact choice of coefficients from wikipedia page for Heun's method :)\n\nReferences\n\n@article{shu1988efficient,\n title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},\n author={Shu, Chi-Wang and Osher, Stanley},\n journal={Journal of computational physics},\n volume={77},\n number={2},\n pages={439--471},\n year={1988},\n publisher={Elsevier}\n}\n@article{ralston1962runge,\n title={Runge-Kutta methods with minimum error bounds},\n author={Ralston, Anthony},\n journal={Mathematics of computation},\n volume={16},\n number={80},\n pages={431--437},\n year={1962},\n doi={10.1090/S0025-5718-1962-0150954-0}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK33ShuOsher","page":"Algorithms","title":"TimeMachine.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988)\n\nReferences\n\n@article{shu1988efficient,\n title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},\n author={Shu, Chi-Wang and Osher, Stanley},\n journal={Journal of computational physics},\n volume={77},\n number={2},\n pages={439--471},\n year={1988},\n publisher={Elsevier}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK34SpiteriRuuth","page":"Algorithms","title":"TimeMachine.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Spiteri and Ruuth (1988)\n\nReferences\n\n@article{spiteri2002new,\n title={A new class of optimal high-order strong-stability-preserving time discretization methods},\n author={Spiteri, Raymond J and Ruuth, Steven J},\n journal={SIAM Journal on Numerical Analysis},\n volume={40},\n number={2},\n pages={469--491},\n year={2002},\n publisher={SIAM}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#TimeMachine.ARK1ForwardBackwardEuler","page":"Algorithms","title":"TimeMachine.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme, combining a forward Euler explicit step with a backward Euler implicit correction.\n\nReferences\n\nAscher, U.M.; Ruuth, S.J. and Spiteri, R.S. (1997) \"Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations\", Applied Numerical Mathematics, 25(2-3): 151–167. doi: 10.1016/S0168-9274(97)00056-1\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"TimeMachine.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme, combining the implicit and explicit midpoint methods.\n\nReferences\n\nAscher, U.M.; Ruuth, S.J. and Spiteri, R.S. (1997) \"Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations\", Applied Numerical Mathematics, 25(2-3): 151–167. doi: 10.1016/S0168-9274(97)00056-1\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"TimeMachine.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of Giraldo, Kelly and Constantinescu (2013).\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\nReferences\n\nGiraldo, F.X.; Kelly, J.F. and Constantinescu, E.M. (2013) \"Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA)\", SIAM Journal on Scientific Computing, 35(5): B1162–B1194 doi: 10.1137/120876034\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Kennedy and Carpenter (2019).\n\nReferences\n\nKennedy, C.A. and Carpenter, M.H. (2019) \"Higher-order additive Runge–Kutta schemes for ordinary differential equations\" Applied Numerical Mathematics. 136: 183–205. doi: 10.1016/j.apnum.2018.10.007\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Kennedy and Carpenter (2019).\n\nReferences\n\nKennedy, C.A. and Carpenter, M.H. (2019) \"Higher-order additive Runge–Kutta schemes for ordinary differential equations\" Applied Numerical Mathematics. 136: 183–205. doi: 10.1016/j.apnum.2018.10.007\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR11/siteinfo.js b/previews/PR11/siteinfo.js
new file mode 100644
index 000000000..06c127a09
--- /dev/null
+++ b/previews/PR11/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR11";
diff --git a/previews/PR115/algorithms/index.html b/previews/PR115/algorithms/index.html
new file mode 100644
index 000000000..bee3fb056
--- /dev/null
+++ b/previews/PR115/algorithms/index.html
@@ -0,0 +1,5 @@
+
+Algorithms · ClimaTimeSteppers
A generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.
Generates an IMEXARKTableau struct from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.
The convergence orders of the provided methods are verified using test cases from ARKode. Plots of the solutions to these test cases, the errors of these solutions, and the convergence orders with respect to dt are shown below.
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.23 on Friday 23 December 2022. Using Julia version 1.8.3.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
This document was generated with Documenter.jl version 0.27.23 on Friday 23 December 2022. Using Julia version 1.8.3.
diff --git a/previews/PR115/search_index.js b/previews/PR115/search_index.js
new file mode 100644
index 000000000..011b7e7b4
--- /dev/null
+++ b/previews/PR115/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"newtons_method/#Newton's-Method","page":"Newton's Method","title":"Newton's Method","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"NewtonsMethod","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newton's Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Newton-Krylov-Method","page":"Newton's Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newton's Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newton's Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newton's Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newton's Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newton's Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newton's Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newton's Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newton's Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Convergence-Conditions","page":"Newton's Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newton's Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newton's Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newton's Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newton's Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newton's Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newton's Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newton's Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Update-Signals","page":"Newton's Method","title":"Update Signals","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newton's Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newton's Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newton's Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,,) == A*u for some A (matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"algorithms/#Interface-and-OrdinaryDiffEq-compatibility","page":"Algorithms","title":"Interface and OrdinaryDiffEq compatibility","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ForwardEulerODEFunction","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"Algorithms","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#IMEX-ARK-methods","page":"Algorithms","title":"IMEX ARK methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"IMEXARKAlgorithm\nIMEXARKTableau","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.IMEXARKAlgorithm","page":"Algorithms","title":"ClimaTimeSteppers.IMEXARKAlgorithm","text":"IMEXARKAlgorithm(\n tabname::AbstractTableau,\n newtons_method\n) <: DistributedODEAlgorithm\n\nA generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.IMEXARKTableau","page":"Algorithms","title":"ClimaTimeSteppers.IMEXARKTableau","text":"IMEXARKTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nGenerates an IMEXARKTableau struct from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"The convergence orders of the provided methods are verified using test cases from ARKode. Plots of the solutions to these test cases, the errors of these solutions, and the convergence orders with respect to dt are shown below.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"using Pkg\nPkg.activate(\"../../test\")\nPkg.instantiate()\ninclude(\"../../test/convergence.jl\")\nPkg.activate(\".\")","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Plots for ark_analytic: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Plots for ark_analytic_nonlin: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Plots for ark_analytic_sys: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ARS","page":"Algorithms","title":"ARS","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARS111\nARS121\nARS232\nARS343","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.ARS111","page":"Algorithms","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nThe Forward-Backward (1,1,1) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.1.\n\nThis is equivalent to the OrdinaryDiffEq.IMEXEuler algorithm.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARS121","page":"Algorithms","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nThe Forward-Backward (1,2,1) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.2.\n\nThis is equivalent to the OrdinaryDiffEq.IMEXEulerARK algorithm.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARS232","page":"Algorithms","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nThe Forward-Backward (2,3,2) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.5.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARS343","page":"Algorithms","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nThe L-stable, third-order (3,4,3) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.7.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR115/siteinfo.js b/previews/PR115/siteinfo.js
new file mode 100644
index 000000000..732b865ac
--- /dev/null
+++ b/previews/PR115/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR115";
diff --git a/previews/PR13/algorithms/index.html b/previews/PR13/algorithms/index.html
new file mode 100644
index 000000000..2a5bd9567
--- /dev/null
+++ b/previews/PR13/algorithms/index.html
@@ -0,0 +1,57 @@
+
+Algorithms · TimeMachine
The second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Heun's method.) Exact choice of coefficients from wikipedia page for Heun's method :)
References
@article{shu1988efficient,
+ title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},
+ author={Shu, Chi-Wang and Osher, Stanley},
+ journal={Journal of computational physics},
+ volume={77},
+ number={2},
+ pages={439--471},
+ year={1988},
+ publisher={Elsevier}
+}
+@article {Heun1900,
+ title = {Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabh"{a}ngigen Ver"{a}nderlichen}
+ author = {Heun, Karl},
+ journal = {Z. Math. Phys},
+ volume = {45},
+ pages = {23--38},
+ year = {1900}
+}
The second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Ralstons's method.) Exact choice of coefficients from wikipedia page for Heun's method :)
The third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Spiteri and Ruuth (1988)
References
@article{spiteri2002new,
+ title={A new class of optimal high-order strong-stability-preserving time discretization methods},
+ author={Spiteri, Raymond J and Ruuth, Steven J},
+ journal={SIAM Journal on Numerical Analysis},
+ volume={40},
+ number={2},
+ pages={469--491},
+ year={2002},
+ publisher={SIAM}
+}
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of Giraldo, Kelly and Constantinescu (2013).
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
References
Giraldo, F.X.; Kelly, J.F. and Constantinescu, E.M. (2013) "Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA)", SIAM Journal on Scientific Computing, 35(5): B1162–B1194 doi: 10.1137/120876034
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl on Thursday 22 October 2020. Using Julia version 1.5.2.
Schlegel, M., Knoth, O., Arnold, M., and Wolke, R. (2012) "Implementation of multirate time integration methods for air pollution modelling", Geosci. Model Dev., 5, 1395–1405, doi: 10.5194/gmd-5-1395-2012
Settings
This document was generated with Documenter.jl on Thursday 22 October 2020. Using Julia version 1.5.2.
TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
This document was generated with Documenter.jl on Thursday 22 October 2020. Using Julia version 1.5.2.
diff --git a/previews/PR13/search_index.js b/previews/PR13/search_index.js
new file mode 100644
index 000000000..a3bc8e0e5
--- /dev/null
+++ b/previews/PR13/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"background/MultirateRungeKutta/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau \n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/MultirateRungeKutta/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau \n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/MultirateRungeKutta/#References","page":"Multirate Runge Kutta","title":"References","text":"","category":"section"},{"location":"background/MultirateRungeKutta/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Schlegel, M., Knoth, O., Arnold, M., and Wolke, R. (2012) \"Implementation of multirate time integration methods for air pollution modelling\", Geosci. Model Dev., 5, 1395–1405, doi: 10.5194/gmd-5-1395-2012","category":"page"},{"location":"background/LowStorageRungeKutta/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/LowStorageRungeKutta/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/AdditiveRungeKutta/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/AdditiveRungeKutta/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/AdditiveRungeKutta/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = TimeMachine.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.initialize!","page":"Callbacks","title":"TimeMachine.Callbacks.initialize!","text":"TimeMachine.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.finalize!","page":"Callbacks","title":"TimeMachine.Callbacks.finalize!","text":"TimeMachine.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm; \n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"background/StrongStabilityPreservingRungeKutta/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/StrongStabilityPreservingRungeKutta/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/StrongStabilityPreservingRungeKutta/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/StrongStabilityPreservingRungeKutta/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/StrongStabilityPreservingRungeKutta/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"#TimeMachine.jl","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"","category":"section"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#TimeMachine.LSRK54CarpenterKennedy","page":"Algorithms","title":"TimeMachine.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe fourth-order, 5-stage low storage Runge–Kutta scheme from Carpenter and Kennedy (1994). The coefficients are those from Solution 3 in the paper.\n\nReferences\n\nCarpenter, M.H.; Kennedy, C.A. (1994) \"Fourth-order 2N-storage Runge–Kutta schemes\", NASA Technical Memorandum 109112. http://hdl.handle.net/2060/19940028444\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"TimeMachine.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe fourth-order, 14-stage, low-storage, Runge–Kutta scheme of Niegemann, Diehl, and Busch (2012) with optimized stability region\n\nReferences\n\nNiegemann, J.; Diehl, R.; Busch, K. (2012) \"Efficient low-storage Runge–Kutta schemes with optimized stability regions\", Journal of Computational Physics 231(2): 364–372. doi: 10.1016/j.jcp.2011.09.003\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRKEulerMethod","page":"Algorithms","title":"TimeMachine.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"SSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#TimeMachine.SSPRK22Heuns","page":"Algorithms","title":"TimeMachine.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Heun's method.) Exact choice of coefficients from wikipedia page for Heun's method :)\n\nReferences\n\n@article{shu1988efficient,\n title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},\n author={Shu, Chi-Wang and Osher, Stanley},\n journal={Journal of computational physics},\n volume={77},\n number={2},\n pages={439--471},\n year={1988},\n publisher={Elsevier}\n}\n@article {Heun1900,\n title = {Neue Methoden zur approximativen Integration der\n Differentialgleichungen einer unabh\"{a}ngigen Ver\"{a}nderlichen}\n author = {Heun, Karl},\n journal = {Z. Math. Phys},\n volume = {45},\n pages = {23--38},\n year = {1900}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Ralstons","page":"Algorithms","title":"TimeMachine.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Ralstons's method.) Exact choice of coefficients from wikipedia page for Heun's method :)\n\nReferences\n\n@article{shu1988efficient,\n title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},\n author={Shu, Chi-Wang and Osher, Stanley},\n journal={Journal of computational physics},\n volume={77},\n number={2},\n pages={439--471},\n year={1988},\n publisher={Elsevier}\n}\n@article{ralston1962runge,\n title={Runge-Kutta methods with minimum error bounds},\n author={Ralston, Anthony},\n journal={Mathematics of computation},\n volume={16},\n number={80},\n pages={431--437},\n year={1962},\n doi={10.1090/S0025-5718-1962-0150954-0}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK33ShuOsher","page":"Algorithms","title":"TimeMachine.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988)\n\nReferences\n\n@article{shu1988efficient,\n title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},\n author={Shu, Chi-Wang and Osher, Stanley},\n journal={Journal of computational physics},\n volume={77},\n number={2},\n pages={439--471},\n year={1988},\n publisher={Elsevier}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK34SpiteriRuuth","page":"Algorithms","title":"TimeMachine.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Spiteri and Ruuth (1988)\n\nReferences\n\n@article{spiteri2002new,\n title={A new class of optimal high-order strong-stability-preserving time discretization methods},\n author={Spiteri, Raymond J and Ruuth, Steven J},\n journal={SIAM Journal on Numerical Analysis},\n volume={40},\n number={2},\n pages={469--491},\n year={2002},\n publisher={SIAM}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#TimeMachine.ARK1ForwardBackwardEuler","page":"Algorithms","title":"TimeMachine.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme, combining a forward Euler explicit step with a backward Euler implicit correction.\n\nReferences\n\nAscher, U.M.; Ruuth, S.J. and Spiteri, R.S. (1997) \"Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations\", Applied Numerical Mathematics, 25(2-3): 151–167. doi: 10.1016/S0168-9274(97)00056-1\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"TimeMachine.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme, combining the implicit and explicit midpoint methods.\n\nReferences\n\nAscher, U.M.; Ruuth, S.J. and Spiteri, R.S. (1997) \"Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations\", Applied Numerical Mathematics, 25(2-3): 151–167. doi: 10.1016/S0168-9274(97)00056-1\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"TimeMachine.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of Giraldo, Kelly and Constantinescu (2013).\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\nReferences\n\nGiraldo, F.X.; Kelly, J.F. and Constantinescu, E.M. (2013) \"Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA)\", SIAM Journal on Scientific Computing, 35(5): B1162–B1194 doi: 10.1137/120876034\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Kennedy and Carpenter (2019).\n\nReferences\n\nKennedy, C.A. and Carpenter, M.H. (2019) \"Higher-order additive Runge–Kutta schemes for ordinary differential equations\" Applied Numerical Mathematics. 136: 183–205. doi: 10.1016/j.apnum.2018.10.007\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Kennedy and Carpenter (2019).\n\nReferences\n\nKennedy, C.A. and Carpenter, M.H. (2019) \"Higher-order additive Runge–Kutta schemes for ordinary differential equations\" Applied Numerical Mathematics. 136: 183–205. doi: 10.1016/j.apnum.2018.10.007\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR13/siteinfo.js b/previews/PR13/siteinfo.js
new file mode 100644
index 000000000..29dd8923b
--- /dev/null
+++ b/previews/PR13/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR13";
diff --git a/previews/PR14/algorithms/index.html b/previews/PR14/algorithms/index.html
new file mode 100644
index 000000000..71bf50040
--- /dev/null
+++ b/previews/PR14/algorithms/index.html
@@ -0,0 +1,2 @@
+
+Algorithms · TimeMachine
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl on Tuesday 27 October 2020. Using Julia version 1.5.2.
Schlegel, M., Knoth, O., Arnold, M., and Wolke, R. (2012) "Implementation of multirate time integration methods for air pollution modelling", Geosci. Model Dev., 5, 1395–1405, doi: 10.5194/gmd-5-1395-2012
Settings
This document was generated with Documenter.jl on Tuesday 27 October 2020. Using Julia version 1.5.2.
TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter , Christopher A Kennedy (1994), Fourth-order $2N$-storage Runge--Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center , Hampton , VA, 1994.
+
This document was generated with Documenter.jl on Tuesday 27 October 2020. Using Julia version 1.5.2.
diff --git a/previews/PR14/search_index.js b/previews/PR14/search_index.js
new file mode 100644
index 000000000..f41394ff3
--- /dev/null
+++ b/previews/PR14/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau \n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau \n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#References","page":"Multirate Runge Kutta","title":"References","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Schlegel, M., Knoth, O., Arnold, M., and Wolke, R. (2012) \"Implementation of multirate time integration methods for air pollution modelling\", Geosci. Model Dev., 5, 1395–1405, doi: 10.5194/gmd-5-1395-2012","category":"page"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = TimeMachine.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.initialize!","page":"Callbacks","title":"TimeMachine.Callbacks.initialize!","text":"TimeMachine.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.finalize!","page":"Callbacks","title":"TimeMachine.Callbacks.finalize!","text":"TimeMachine.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm; \n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"#TimeMachine.jl","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"","category":"section"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#TimeMachine.LSRK54CarpenterKennedy","page":"Algorithms","title":"TimeMachine.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe fourth-order, 5-stage low storage Runge–Kutta scheme from Solution 3 of Mark H Carpenter , Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"TimeMachine.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe fourth-order, 14-stage, low-storage, Runge–Kutta scheme of Jens Niegemann , Richard Diehl , Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRKEulerMethod","page":"Algorithms","title":"TimeMachine.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"SSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#TimeMachine.SSPRK22Heuns","page":"Algorithms","title":"TimeMachine.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Ralstons","page":"Algorithms","title":"TimeMachine.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK33ShuOsher","page":"Algorithms","title":"TimeMachine.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK34SpiteriRuuth","page":"Algorithms","title":"TimeMachine.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri , Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#TimeMachine.ARK1ForwardBackwardEuler","page":"Algorithms","title":"TimeMachine.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher , Steven J. Ruuth , Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"TimeMachine.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher , Steven J. Ruuth , Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"TimeMachine.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy , Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy , Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR14/siteinfo.js b/previews/PR14/siteinfo.js
new file mode 100644
index 000000000..0c6082e2a
--- /dev/null
+++ b/previews/PR14/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR14";
diff --git a/previews/PR149/algo_formulations/ark/index.html b/previews/PR149/algo_formulations/ark/index.html
new file mode 100644
index 000000000..f22828b48
--- /dev/null
+++ b/previews/PR149/algo_formulations/ark/index.html
@@ -0,0 +1,14 @@
+
+Additive Runge–Kutta · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.23 on Friday 6 January 2023. Using Julia version 1.8.4.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
A generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.
Generates an IMEXARKTableau struct from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractTableau)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
+
+
Settings
This document was generated with Documenter.jl version 0.27.23 on Friday 6 January 2023. Using Julia version 1.8.4.
This document was generated with Documenter.jl version 0.27.23 on Friday 6 January 2023. Using Julia version 1.8.4.
diff --git a/previews/PR149/search_index.js b/previews/PR149/search_index.js
new file mode 100644
index 000000000..b6c817485
--- /dev/null
+++ b/previews/PR149/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"algo_formulations/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"api/nl_solvers/#Newton's-Method","page":"Non-linear solvers","title":"Newton's Method","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"NewtonsMethod","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewtonsMethod","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Newton-Krylov-Method","page":"Non-linear solvers","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.KrylovMethod","page":"Non-linear solvers","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForcingTerm","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ConstantForcing","page":"Non-linear solvers","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Non-linear solvers","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Non-linear solvers","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.PrintConditionNumber","page":"Non-linear solvers","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Jacobian-free-Newton-Krylov-Method","page":"Non-linear solvers","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.JacobianFreeJVP","page":"Non-linear solvers","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffJVP","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Convergence-Conditions","page":"Non-linear solvers","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ConvergenceChecker","page":"Non-linear solvers","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ConvergenceCondition","page":"Non-linear solvers","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MaximumError","page":"Non-linear solvers","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MaximumRelativeError","page":"Non-linear solvers","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MaximumErrorReduction","page":"Non-linear solvers","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Non-linear solvers","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MultipleConditions","page":"Non-linear solvers","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Update-Signals","page":"Non-linear solvers","title":"Update Signals","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateSignalHandler","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateEvery","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateEveryN","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateEveryDt","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateSignal","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewTimeStep","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewNewtonSolve","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewNewtonIteration","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algo_formulations/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"algo_formulations/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"algo_formulations/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"algo_formulations/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"algo_formulations/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"dev/report_gen/#Report-generator","page":"Report generator","title":"Report generator","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In this section, we create a report comparing the solution errors and convergence orders for several test problems and algorithms.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots for ark_analytic: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots for ark_analytic_nonlin: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots for ark_analytic_sys: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)","category":"page"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractTableau)","category":"page"},{"location":"algo_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"algo_formulations/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algo_formulations/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algo_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algo_formulations/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"nl_solvers/formulation/#Non-linear-solvers-formulation","page":"Formulation","title":"Non-linear solvers formulation","text":"","category":"section"},{"location":"nl_solvers/formulation/#Newton's-method","page":"Formulation","title":"Newton's method","text":"","category":"section"},{"location":"nl_solvers/formulation/","page":"Formulation","title":"Formulation","text":"TODO: fill out","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"},{"location":"api/algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/algorithms/#Interface-and-OrdinaryDiffEq-compatibility","page":"Algorithms","title":"Interface and OrdinaryDiffEq compatibility","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"ForwardEulerODEFunction","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"Algorithms","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#IMEX-ARK-methods","page":"Algorithms","title":"IMEX ARK methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"IMEXARKAlgorithm\nIMEXARKTableau","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.IMEXARKAlgorithm","page":"Algorithms","title":"ClimaTimeSteppers.IMEXARKAlgorithm","text":"IMEXARKAlgorithm(\n tabname::AbstractTableau,\n newtons_method\n) <: DistributedODEAlgorithm\n\nA generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.IMEXARKTableau","page":"Algorithms","title":"ClimaTimeSteppers.IMEXARKTableau","text":"IMEXARKTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nGenerates an IMEXARKTableau struct from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ARS","page":"Algorithms","title":"ARS","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"ARS111\nARS121\nARS232\nARS343","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS111","page":"Algorithms","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nThe Forward-Backward (1,1,1) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.1.\n\nThis is equivalent to the OrdinaryDiffEq.IMEXEuler algorithm.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS121","page":"Algorithms","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nThe Forward-Backward (1,2,1) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.2.\n\nThis is equivalent to the OrdinaryDiffEq.IMEXEulerARK algorithm.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS232","page":"Algorithms","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nThe Forward-Backward (2,3,2) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.5.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS343","page":"Algorithms","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nThe L-stable, third-order (3,4,3) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.7.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR149/siteinfo.js b/previews/PR149/siteinfo.js
new file mode 100644
index 000000000..3dbf091f5
--- /dev/null
+++ b/previews/PR149/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR149";
diff --git a/previews/PR149/test_problems/diffusion_2d/index.html b/previews/PR149/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..969b0a6f7
--- /dev/null
+++ b/previews/PR149/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl on Friday 30 October 2020. Using Julia version 1.5.2.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter , Christopher A Kennedy (1994), Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center , Hampton , VA, 1994.
+
This document was generated with Documenter.jl on Friday 30 October 2020. Using Julia version 1.5.2.
diff --git a/previews/PR15/search_index.js b/previews/PR15/search_index.js
new file mode 100644
index 000000000..726ac5f7e
--- /dev/null
+++ b/previews/PR15/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel , O. Knoth , M. Arnold , R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J { \\ \" o } rg Wensch , Oswald Knoth , Alexander Galant (2009), Oswald Knoth , Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker , William C Skamarock (1998) and Louis J Wicker , William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = TimeMachine.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.initialize!","page":"Callbacks","title":"TimeMachine.Callbacks.initialize!","text":"TimeMachine.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.finalize!","page":"Callbacks","title":"TimeMachine.Callbacks.finalize!","text":"TimeMachine.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm; \n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"#TimeMachine.jl","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"","category":"section"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = TimeMachine","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#TimeMachine.LowStorageRungeKutta2N","page":"Algorithms","title":"TimeMachine.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK54CarpenterKennedy","page":"Algorithms","title":"TimeMachine.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter , Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"TimeMachine.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann , Richard Diehl , Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRKEulerMethod","page":"Algorithms","title":"TimeMachine.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#TimeMachine.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"TimeMachine.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Heuns","page":"Algorithms","title":"TimeMachine.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Ralstons","page":"Algorithms","title":"TimeMachine.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK33ShuOsher","page":"Algorithms","title":"TimeMachine.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK34SpiteriRuuth","page":"Algorithms","title":"TimeMachine.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri , Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#TimeMachine.AdditiveRungeKutta","page":"Algorithms","title":"TimeMachine.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK1ForwardBackwardEuler","page":"Algorithms","title":"TimeMachine.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher , Steven J. Ruuth , Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"TimeMachine.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher , Steven J. Ruuth , Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"TimeMachine.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy , Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy , Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#TimeMachine.Multirate","page":"Algorithms","title":"TimeMachine.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#TimeMachine.MultirateInfinitesimalStep","page":"Algorithms","title":"TimeMachine.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J { \\ \" o } rg Wensch , Oswald Knoth , Alexander Galant (2009) and Oswald Knoth , Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS2","page":"Algorithms","title":"TimeMachine.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS3C","page":"Algorithms","title":"TimeMachine.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS4","page":"Algorithms","title":"TimeMachine.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS4a","page":"Algorithms","title":"TimeMachine.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.TVDMISA","page":"Algorithms","title":"TimeMachine.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.TVDMISB","page":"Algorithms","title":"TimeMachine.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#TimeMachine.WickerSkamarockRungeKutta","page":"Algorithms","title":"TimeMachine.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker , William C Skamarock (1998) and Louis J Wicker , William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.WSRK2","page":"Algorithms","title":"TimeMachine.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker , William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.WSRK3","page":"Algorithms","title":"TimeMachine.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker , William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR15/siteinfo.js b/previews/PR15/siteinfo.js
new file mode 100644
index 000000000..30e37c7fa
--- /dev/null
+++ b/previews/PR15/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR15";
diff --git a/previews/PR158/algo_formulations/ark/index.html b/previews/PR158/algo_formulations/ark/index.html
new file mode 100644
index 000000000..c22b03c52
--- /dev/null
+++ b/previews/PR158/algo_formulations/ark/index.html
@@ -0,0 +1,14 @@
+
+Additive Runge–Kutta · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.23 on Thursday 12 January 2023. Using Julia version 1.8.5.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
A mechanism for restricting which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXAlgorithmName.
The last constructor matches the notation of OrdinaryDiffEq.jl; it dispatches to the second constructor by returning IMEXAlgorithm(Name(), newtons_method).
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Family of SSP333 algorithms parametrized by the value β, from Section 3.2 of https://arxiv.org/pdf/1702.04621.pdf. The default value of β, 1/2 + √3/6, results in an SDIRK algorithm, which is also called SSP3(333)c in https://gmd.copernicus.org/articles/11/1497/2018/gmd-11-1497-2018.pdf.
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
+
+
Settings
This document was generated with Documenter.jl version 0.27.23 on Thursday 12 January 2023. Using Julia version 1.8.5.
This document was generated with Documenter.jl version 0.27.23 on Thursday 12 January 2023. Using Julia version 1.8.5.
diff --git a/previews/PR158/search_index.js b/previews/PR158/search_index.js
new file mode 100644
index 000000000..14565f7e1
--- /dev/null
+++ b/previews/PR158/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"algo_formulations/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algo_formulations/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"api/nl_solvers/#Newton's-Method","page":"Non-linear solvers","title":"Newton's Method","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"NewtonsMethod","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewtonsMethod","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Newton-Krylov-Method","page":"Non-linear solvers","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.KrylovMethod","page":"Non-linear solvers","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForcingTerm","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ConstantForcing","page":"Non-linear solvers","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Non-linear solvers","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Non-linear solvers","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.PrintConditionNumber","page":"Non-linear solvers","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Jacobian-free-Newton-Krylov-Method","page":"Non-linear solvers","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.JacobianFreeJVP","page":"Non-linear solvers","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffJVP","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Non-linear solvers","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Convergence-Conditions","page":"Non-linear solvers","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ConvergenceChecker","page":"Non-linear solvers","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.ConvergenceCondition","page":"Non-linear solvers","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MaximumError","page":"Non-linear solvers","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MaximumRelativeError","page":"Non-linear solvers","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MaximumErrorReduction","page":"Non-linear solvers","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Non-linear solvers","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.MultipleConditions","page":"Non-linear solvers","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#Update-Signals","page":"Non-linear solvers","title":"Update Signals","text":"","category":"section"},{"location":"api/nl_solvers/","page":"Non-linear solvers","title":"Non-linear solvers","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateSignalHandler","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateEvery","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateEveryN","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateEveryDt","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.UpdateSignal","page":"Non-linear solvers","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewTimeStep","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewNewtonSolve","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/nl_solvers/#ClimaTimeSteppers.NewNewtonIteration","page":"Non-linear solvers","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algo_formulations/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"algo_formulations/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"algo_formulations/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"algo_formulations/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"algo_formulations/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"algo_formulations/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"dev/report_gen/#Report-generator","page":"Report generator","title":"Report generator","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In this section, we create a report comparing the solution errors and convergence orders for several test problems and algorithms.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots for ark_analytic: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots for ark_analytic_nonlin: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots for ark_analytic_sys: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)","category":"page"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"algo_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algo_formulations/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"algo_formulations/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algo_formulations/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algo_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algo_formulations/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algo_formulations/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"nl_solvers/formulation/#Non-linear-solvers-formulation","page":"Formulation","title":"Non-linear solvers formulation","text":"","category":"section"},{"location":"nl_solvers/formulation/#Newton's-method","page":"Formulation","title":"Newton's method","text":"","category":"section"},{"location":"nl_solvers/formulation/","page":"Formulation","title":"Formulation","text":"TODO: fill out","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"},{"location":"api/algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/algorithms/#Interface-and-OrdinaryDiffEq-compatibility","page":"Algorithms","title":"Interface and OrdinaryDiffEq compatibility","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"ForwardEulerODEFunction\nAbstractAlgorithmConstraint\nUnconstrained\nSSPConstrained\nIMEXAlgorithm\nIMEXTableau","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"Algorithms","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"Algorithms","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for restricting which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.Unconstrained","page":"Algorithms","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPConstrained","page":"Algorithms","title":"ClimaTimeSteppers.SSPConstrained","text":"SSPConstrained\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.IMEXAlgorithm","page":"Algorithms","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n[Name](newtons_method)\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXAlgorithmName.\n\nThe last constructor matches the notation of OrdinaryDiffEq.jl; it dispatches to the second constructor by returning IMEXAlgorithm(Name(), newtons_method).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.IMEXTableau","page":"Algorithms","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#IMEX-SSP-methods","page":"Algorithms","title":"IMEX SSP methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"SSP433\nSSP222\nSSP332\nSSP333\nSSP322","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.SSP433","page":"Algorithms","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nhttps://link.springer.com/content/pdf/10.1007/BF02728986.pdf, Table VI\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSP222","page":"Algorithms","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nhttps://link.springer.com/content/pdf/10.1007/BF02728986.pdf, Table II\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSP332","page":"Algorithms","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nhttps://link.springer.com/content/pdf/10.1007/BF02728986.pdf, Table V\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSP333","page":"Algorithms","title":"ClimaTimeSteppers.SSP333","text":"SSP333([β])\n\nFamily of SSP333 algorithms parametrized by the value β, from Section 3.2 of https://arxiv.org/pdf/1702.04621.pdf. The default value of β, 1/2 + √3/6, results in an SDIRK algorithm, which is also called SSP3(333)c in https://gmd.copernicus.org/articles/11/1497/2018/gmd-11-1497-2018.pdf.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSP322","page":"Algorithms","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nhttps://link.springer.com/content/pdf/10.1007/BF02728986.pdf, Table III\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ARS","page":"Algorithms","title":"ARS","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"ARS111\nARS121\nARS232\nARS343","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS111","page":"Algorithms","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nThe Forward-Backward (1,1,1) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.1.\n\nThis is equivalent to the OrdinaryDiffEq.IMEXEuler algorithm.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS121","page":"Algorithms","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nThe Forward-Backward (1,2,1) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.2.\n\nThis is equivalent to the OrdinaryDiffEq.IMEXEulerARK algorithm.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS232","page":"Algorithms","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nThe Forward-Backward (2,3,2) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.5.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.ARS343","page":"Algorithms","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nThe L-stable, third-order (3,4,3) implicit-explicit (IMEX) Runge-Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2.7.\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"api/algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR158/siteinfo.js b/previews/PR158/siteinfo.js
new file mode 100644
index 000000000..a65955f9d
--- /dev/null
+++ b/previews/PR158/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR158";
diff --git a/previews/PR158/test_problems/diffusion_2d/index.html b/previews/PR158/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..7169a3fcd
--- /dev/null
+++ b/previews/PR158/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.23 on Wednesday 1 February 2023. Using Julia version 1.8.5.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
An IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
This document was generated with Documenter.jl version 0.27.23 on Wednesday 1 February 2023. Using Julia version 1.8.5.
diff --git a/previews/PR165/search_index.js b/previews/PR165/search_index.js
new file mode 100644
index 000000000..e2f289bcf
--- /dev/null
+++ b/previews/PR165/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from Sidafa Conde, Sigal Gottlieb, Zachary J. Grant, John N. Shadid (2017), Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from Christopher J. Vogl, Andrew Steyer, Daniel R. Reynolds, Paul A. Ullrich, Carol S. Woodward (2019), Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from Oksana Guba, Mark A. Taylor, Andrew M. Bradley, Peter A. Bosler, Andrew Steyer (2020), section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 2 stages and 2nd order accuracy. Also called Heun's method (Karl Heun (1900)).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR165/siteinfo.js b/previews/PR165/siteinfo.js
new file mode 100644
index 000000000..64383f9f2
--- /dev/null
+++ b/previews/PR165/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR165";
diff --git a/previews/PR165/test_problems/diffusion_2d/index.html b/previews/PR165/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..42e519b56
--- /dev/null
+++ b/previews/PR165/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.23 on Wednesday 1 February 2023. Using Julia version 1.8.5.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
An IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
This document was generated with Documenter.jl version 0.27.23 on Wednesday 1 February 2023. Using Julia version 1.8.5.
diff --git a/previews/PR168/search_index.js b/previews/PR168/search_index.js
new file mode 100644
index 000000000..e2f289bcf
--- /dev/null
+++ b/previews/PR168/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from Sidafa Conde, Sigal Gottlieb, Zachary J. Grant, John N. Shadid (2017), Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from Christopher J. Vogl, Andrew Steyer, Daniel R. Reynolds, Paul A. Ullrich, Carol S. Woodward (2019), Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from Oksana Guba, Mark A. Taylor, Andrew M. Bradley, Peter A. Bosler, Andrew Steyer (2020), section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 2 stages and 2nd order accuracy. Also called Heun's method (Karl Heun (1900)).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR168/siteinfo.js b/previews/PR168/siteinfo.js
new file mode 100644
index 000000000..d2e871b4f
--- /dev/null
+++ b/previews/PR168/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR168";
diff --git a/previews/PR168/test_problems/diffusion_2d/index.html b/previews/PR168/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..1422724ba
--- /dev/null
+++ b/previews/PR168/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.23 on Friday 10 March 2023. Using Julia version 1.8.5.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
An IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
This document was generated with Documenter.jl version 0.27.23 on Friday 10 March 2023. Using Julia version 1.8.5.
diff --git a/previews/PR174/search_index.js b/previews/PR174/search_index.js
new file mode 100644
index 000000000..e2f289bcf
--- /dev/null
+++ b/previews/PR174/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from Sidafa Conde, Sigal Gottlieb, Zachary J. Grant, John N. Shadid (2017), Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from Christopher J. Vogl, Andrew Steyer, Daniel R. Reynolds, Paul A. Ullrich, Carol S. Woodward (2019), Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from Oksana Guba, Mark A. Taylor, Andrew M. Bradley, Peter A. Bosler, Andrew Steyer (2020), section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 2 stages and 2nd order accuracy. Also called Heun's method (Karl Heun (1900)).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR174/siteinfo.js b/previews/PR174/siteinfo.js
new file mode 100644
index 000000000..c63af5559
--- /dev/null
+++ b/previews/PR174/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR174";
diff --git a/previews/PR174/test_problems/diffusion_2d/index.html b/previews/PR174/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..703e42b42
--- /dev/null
+++ b/previews/PR174/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.24 on Monday 22 May 2023. Using Julia version 1.8.5.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
An IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
This document was generated with Documenter.jl version 0.27.24 on Monday 22 May 2023. Using Julia version 1.8.5.
diff --git a/previews/PR182/search_index.js b/previews/PR182/search_index.js
new file mode 100644
index 000000000..e2f289bcf
--- /dev/null
+++ b/previews/PR182/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from Sidafa Conde, Sigal Gottlieb, Zachary J. Grant, John N. Shadid (2017), Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from Christopher J. Vogl, Andrew Steyer, Daniel R. Reynolds, Paul A. Ullrich, Carol S. Woodward (2019), Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from Oksana Guba, Mark A. Taylor, Andrew M. Bradley, Peter A. Bosler, Andrew Steyer (2020), section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 2 stages and 2nd order accuracy. Also called Heun's method (Karl Heun (1900)).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR182/siteinfo.js b/previews/PR182/siteinfo.js
new file mode 100644
index 000000000..40a94bea1
--- /dev/null
+++ b/previews/PR182/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR182";
diff --git a/previews/PR182/test_problems/diffusion_2d/index.html b/previews/PR182/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..4473d7654
--- /dev/null
+++ b/previews/PR182/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl on Monday 2 November 2020. Using Julia version 1.5.2.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter , Christopher A Kennedy (1994), Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center , Hampton , VA, 1994.
+
This document was generated with Documenter.jl on Monday 2 November 2020. Using Julia version 1.5.2.
diff --git a/previews/PR19/search_index.js b/previews/PR19/search_index.js
new file mode 100644
index 000000000..726ac5f7e
--- /dev/null
+++ b/previews/PR19/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel , O. Knoth , M. Arnold , R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J { \\ \" o } rg Wensch , Oswald Knoth , Alexander Galant (2009), Oswald Knoth , Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker , William C Skamarock (1998) and Louis J Wicker , William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = TimeMachine.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.initialize!","page":"Callbacks","title":"TimeMachine.Callbacks.initialize!","text":"TimeMachine.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.finalize!","page":"Callbacks","title":"TimeMachine.Callbacks.finalize!","text":"TimeMachine.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm; \n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"#TimeMachine.jl","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"","category":"section"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = TimeMachine","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#TimeMachine.LowStorageRungeKutta2N","page":"Algorithms","title":"TimeMachine.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK54CarpenterKennedy","page":"Algorithms","title":"TimeMachine.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter , Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"TimeMachine.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann , Richard Diehl , Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRKEulerMethod","page":"Algorithms","title":"TimeMachine.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#TimeMachine.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"TimeMachine.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Heuns","page":"Algorithms","title":"TimeMachine.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Ralstons","page":"Algorithms","title":"TimeMachine.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK33ShuOsher","page":"Algorithms","title":"TimeMachine.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK34SpiteriRuuth","page":"Algorithms","title":"TimeMachine.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri , Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#TimeMachine.AdditiveRungeKutta","page":"Algorithms","title":"TimeMachine.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK1ForwardBackwardEuler","page":"Algorithms","title":"TimeMachine.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher , Steven J. Ruuth , Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"TimeMachine.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher , Steven J. Ruuth , Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"TimeMachine.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy , Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy , Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#TimeMachine.Multirate","page":"Algorithms","title":"TimeMachine.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#TimeMachine.MultirateInfinitesimalStep","page":"Algorithms","title":"TimeMachine.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J { \\ \" o } rg Wensch , Oswald Knoth , Alexander Galant (2009) and Oswald Knoth , Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS2","page":"Algorithms","title":"TimeMachine.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS3C","page":"Algorithms","title":"TimeMachine.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS4","page":"Algorithms","title":"TimeMachine.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS4a","page":"Algorithms","title":"TimeMachine.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.TVDMISA","page":"Algorithms","title":"TimeMachine.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.TVDMISB","page":"Algorithms","title":"TimeMachine.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#TimeMachine.WickerSkamarockRungeKutta","page":"Algorithms","title":"TimeMachine.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker , William C Skamarock (1998) and Louis J Wicker , William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.WSRK2","page":"Algorithms","title":"TimeMachine.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker , William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.WSRK3","page":"Algorithms","title":"TimeMachine.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker , William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR19/siteinfo.js b/previews/PR19/siteinfo.js
new file mode 100644
index 000000000..97d10c4e4
--- /dev/null
+++ b/previews/PR19/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR19";
diff --git a/previews/PR190/algorithm_formulations/lsrk/index.html b/previews/PR190/algorithm_formulations/lsrk/index.html
new file mode 100644
index 000000000..d25c2a816
--- /dev/null
+++ b/previews/PR190/algorithm_formulations/lsrk/index.html
@@ -0,0 +1,13 @@
+
+Old LSRK Formulations · ClimaTimeSteppers
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.24 on Friday 25 August 2023. Using Julia version 1.8.5.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing, post_stage_callback! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
An IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function apply_filter! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and apply_filter!, where the spatial discretization is implemented using ClimaCore
include("report_gen.jl")
┌ Warning: Order uncertainty too large for RK4 (ark_analytic)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
+┌ Warning: Order uncertainty too large for RK4 (ark_onewaycouple_mri)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with apply_filter! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
+
SM2003
+
+
Endre S{\"u}li, David Mayers, An Introduction to Numerical Analysis, Cambridge University Press, 2003.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
This document was generated with Documenter.jl version 0.27.24 on Friday 25 August 2023. Using Julia version 1.8.5.
diff --git a/previews/PR190/search_index.js b/previews/PR190/search_index.js
new file mode 100644
index 000000000..a06419b9e
--- /dev/null
+++ b/previews/PR190/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function apply_filter! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and apply_filter!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with apply_filter! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from Sidafa Conde, Sigal Gottlieb, Zachary J. Grant, John N. Shadid (2017), Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from Christopher J. Vogl, Andrew Steyer, Daniel R. Reynolds, Paul A. Ullrich, Carol S. Woodward (2019), Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from Oksana Guba, Mark A. Taylor, Andrew M. Bradley, Peter A. Bosler, Andrew Steyer (2020), section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher\nRK4","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 2 stages and 2nd order accuracy. Also called Heun's method (Karl Heun (1900)).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.RK4","page":"ODE Solvers","title":"ClimaTimeSteppers.RK4","text":"RK4\n\nThe RK4 algorithm from Endre S{\\\"u}li, David Mayers (2003), a Runge-Kutta method with 4 stages and 4th order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing, post_stage_callback! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR190/siteinfo.js b/previews/PR190/siteinfo.js
new file mode 100644
index 000000000..654d05fbd
--- /dev/null
+++ b/previews/PR190/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR190";
diff --git a/previews/PR190/test_problems/diffusion_2d/index.html b/previews/PR190/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..42da6693f
--- /dev/null
+++ b/previews/PR190/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.24 on Friday 25 August 2023. Using Julia version 1.8.5.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
An IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore
include("report_gen.jl")
┌ Warning: Order uncertainty too large for RK4 (ark_analytic)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
+┌ Warning: Order uncertainty too large for RK4 (ark_onewaycouple_mri)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
+
SM2003
+
+
Endre S{\"u}li, David Mayers, An Introduction to Numerical Analysis, Cambridge University Press, 2003.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
This document was generated with Documenter.jl version 0.27.24 on Friday 25 August 2023. Using Julia version 1.8.5.
diff --git a/previews/PR191/search_index.js b/previews/PR191/search_index.js
new file mode 100644
index 000000000..51ba5d68c
--- /dev/null
+++ b/previews/PR191/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from Sidafa Conde, Sigal Gottlieb, Zachary J. Grant, John N. Shadid (2017), Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from Christopher J. Vogl, Andrew Steyer, Daniel R. Reynolds, Paul A. Ullrich, Carol S. Woodward (2019), Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from Oksana Guba, Mark A. Taylor, Andrew M. Bradley, Peter A. Bosler, Andrew Steyer (2020), section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher\nRK4","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 2 stages and 2nd order accuracy. Also called Heun's method (Karl Heun (1900)).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.RK4","page":"ODE Solvers","title":"ClimaTimeSteppers.RK4","text":"RK4\n\nThe RK4 algorithm from Endre S{\\\"u}li, David Mayers (2003), a Runge-Kutta method with 4 stages and 4th order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR191/siteinfo.js b/previews/PR191/siteinfo.js
new file mode 100644
index 000000000..c778d887e
--- /dev/null
+++ b/previews/PR191/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR191";
diff --git a/previews/PR191/test_problems/diffusion_2d/index.html b/previews/PR191/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..df07dcb30
--- /dev/null
+++ b/previews/PR191/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.24 on Friday 8 September 2023. Using Julia version 1.8.5.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
An IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore
include("report_gen.jl")
┌ Warning: Order uncertainty too large for RK4 (ark_analytic)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
+┌ Warning: Order uncertainty too large for RK4 (ark_onewaycouple_mri)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
+
SM2003
+
+
Endre S{\"u}li, David Mayers, An Introduction to Numerical Analysis, Cambridge University Press, 2003.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
This document was generated with Documenter.jl version 0.27.24 on Friday 8 September 2023. Using Julia version 1.8.5.
diff --git a/previews/PR195/search_index.js b/previews/PR195/search_index.js
new file mode 100644
index 000000000..51ba5d68c
--- /dev/null
+++ b/previews/PR195/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from Sidafa Conde, Sigal Gottlieb, Zachary J. Grant, John N. Shadid (2017), Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from Christopher J. Vogl, Andrew Steyer, Daniel R. Reynolds, Paul A. Ullrich, Carol S. Woodward (2019), Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from Oksana Guba, Mark A. Taylor, Andrew M. Bradley, Peter A. Bosler, Andrew Steyer (2020), section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher\nRK4","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 2 stages and 2nd order accuracy. Also called Heun's method (Karl Heun (1900)).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.RK4","page":"ODE Solvers","title":"ClimaTimeSteppers.RK4","text":"RK4\n\nThe RK4 algorithm from Endre S{\\\"u}li, David Mayers (2003), a Runge-Kutta method with 4 stages and 4th order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR195/siteinfo.js b/previews/PR195/siteinfo.js
new file mode 100644
index 000000000..b4a2b652c
--- /dev/null
+++ b/previews/PR195/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR195";
diff --git a/previews/PR195/test_problems/diffusion_2d/index.html b/previews/PR195/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..02105c632
--- /dev/null
+++ b/previews/PR195/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.24 on Monday 11 September 2023. Using Julia version 1.8.5.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
An IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.
An IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore
include("report_gen.jl")
┌ Warning: Order uncertainty too large for RK4 (ark_analytic)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
+┌ Warning: Order uncertainty too large for RK4 (ark_onewaycouple_mri)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
+
SM2003
+
+
Endre S{\"u}li, David Mayers, An Introduction to Numerical Analysis, Cambridge University Press, 2003.
R. E. Bank, W. M. Coughran, W. Fichtner, E. H. Grosse, D. J. Rose, R. K. Smith, Transient simulation of silicon devices and circuits, IEEE Transactions on Computer-Aided Design of Integrated
+ Circuits and Systems, 4(4), 436-451, 1985.
+
KennedyCarpenter2016
+
+
C. A. Kennedy, M. H. Carpenter, Diagonally implicit Runge-Kutta methods for ordinary
+ differential equations. A review, Technical Report NASA/TM–2016–219173, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 2016.
+
RobertsSarsharSandu2018arxiv
+
+
Steven Roberts, Arash Sarshar, Adrian Sandu, Coupled Multirate Infinitesimal GARK Schemes for Stiff Systems with
+ Multiple Time Scales, arXiv preprint arXiv:1812.00808, 2019.
This document was generated with Documenter.jl version 0.27.24 on Monday 11 September 2023. Using Julia version 1.8.5.
diff --git a/previews/PR200/search_index.js b/previews/PR200/search_index.js
new file mode 100644
index 000000000..51ba5d68c
--- /dev/null
+++ b/previews/PR200/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see Oksana Guba, Mark Taylor, Amik St-Cyr (2014)), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see Inmaculada Higueras, Teo Roldán (2018)). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from Andrew J. Steyer, Christopher J. Vogl, Mark Taylor, Oksana Guba (2019), Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from Sidafa Conde, Sigal Gottlieb, Zachary J. Grant, John N. Shadid (2017), Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from Lorenzo Pareschi, Giovanni Russo (2005), with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in David J. Gardner, Jorge E. Guerra, François P. Hamon, Daniel R. Reynolds, Paul A. Ullrich, Woodward (2018).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from Christopher J. Vogl, Andrew Steyer, Daniel R. Reynolds, Paul A. Ullrich, Carol S. Woodward (2019), Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from Oksana Guba, Mark A. Taylor, Andrew M. Bradley, Peter A. Bosler, Andrew Steyer (2020), section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from Francis X Giraldo, James F Kelly, Emil M Constantinescu (2013) with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from Christopher A Kennedy, Mark H Carpenter (2019), Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher\nRK4","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 2 stages and 2nd order accuracy. Also called Heun's method (Karl Heun (1900)).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from Chi-Wang Shu, Stanley Osher (1988), with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.RK4","page":"ODE Solvers","title":"ClimaTimeSteppers.RK4","text":"RK4\n\nThe RK4 algorithm from Endre S{\\\"u}li, David Mayers (2003), a Runge-Kutta method with 4 stages and 4th order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR200/siteinfo.js b/previews/PR200/siteinfo.js
new file mode 100644
index 000000000..029974744
--- /dev/null
+++ b/previews/PR200/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR200";
diff --git a/previews/PR200/test_problems/diffusion_2d/index.html b/previews/PR200/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..5206287f9
--- /dev/null
+++ b/previews/PR200/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
An ordinary differential equation (ODE) is an equation of the form
\[\frac{d}{dt}u(t) = T(u(t), t),\]
where $u(t)$ is called the state at time $t$, and $T(u(t), t)$ is called the tendency of the state at time $t$.
The simplest method for numerically solving this equation with a finite timestep$\Delta t$ is the forward Euler method, in which the equation is approximated as
Unlike the forward Euler method, in which $\hat{u}$ is directly computed based on the known state $u_0$, the backward Euler method involves solving a root equation in order to obtain the value of $\hat{u}$. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.
In general, $T$ can be a complicated nonlinear function of $u(t)$ and $t$, and it is usually not possible to solve the backward Euler method's implicit equation for $\hat{u}$ analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for $\hat{u}$. Although this is more computationally expensive than using the forward Euler method to directly obtain $\hat{u}$ from $u_0$, it is often necessary to deal with the problem of stiffness.
Roughly speaking, a tendency $T$ is stiff when the forward Euler method requires a relatively small timestep $\Delta t$ to obtain a reasonably accurate solution, where "relatively small" means that it is smaller than one would expect based on the rate at which $u(t)$ changes over time. When $T$ is not stiff, a small timestep is only required when $u(t)$ changes quickly with respect to $t$, and a larger timestep can be used when $u(t)$ changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when $T$ is stiff.
As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting $T$ into an explicit tendency $T_{\text{exp}}$ and an implicit tendency $T_{\text{imp}}$, so that $T(u(t), t) = T_{\text{exp}}(u(t), t) + T_{\text{imp}}(u(t), t)$, and making the approximation
With this approximation, the implicit equation for $\hat{u}$ becomes
\[u_0 + \Delta t T_{\text{exp}}(u_0, t_0) + \Delta t T_{\text{imp}}(\hat{u}, t_0 + \Delta t) - \hat{u} = 0.\]
Note that $T_{\text{exp}}$ is evaluated explicitly at the known state $u_0$, while $T_{\text{imp}}$ is evaluated implicitly at the unknown state $\hat{u}$.
Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to $\Delta t$ when $\Delta t$ is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order $p$ will have an error that is proportional to $(\Delta t)^p$ for small values of $\Delta t$. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are $s$stages$U_1, U_2, \ldots, U_s$ that satisfy
\[U_i = u_0 + \Delta t \sum_{j = 1}^s a_{i,j} T(U_j, t_0 + \Delta t c_j),\]
and $u(t_0 + \Delta t)$ is approximated as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s b_i T(U_i, t_0 + \Delta t c_i).\]
The coefficients $a_{i,j}$, $b_i$, and $c_i$ of a Runge-Kutta method can be summarized in a Butcher tableau:
Since solving a system of $s$ coupled equations for the stages $U_i$ is usually impractical, many of the $a_{i,j}$ coefficients are set to 0 in commonly used Runge-Kutta methods. When $a_{i,j} = 0$ for all $j \geq i$, the equation for $U_i$ simplifies to the explicit formula
\[U_i = u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j).\]
This is called an explicit Runge-Kutta (ERK) method. When $a_{i,j} = 0$ for all $j > i$, the implicit equation for $U_i$ becomes uncoupled from the equations for the other stages, and it can be rewritten as
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
Since the only unknown tendency in this equation comes from the diagonal coefficient $a_{i,i}$, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where $a_{1,1} = 0$, singly DIRK (SDIRK), where $a_{1,1} = a_{2,2} = \ldots = a_{s,s} = \gamma$ for some constant $\gamma$, and ESDIRK, where $a_{1,1} = 0$ and $a_{2,2} = \ldots = a_{s,s} = \gamma$.
Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients $a_{i,j}$, $b_i$, and $c_i$, and the ERK method has coefficients $\tilde{a}_{i,j}$, $\tilde{b}_i$, and $\tilde{c}_i$, the IMEX ARK method approximates $u(t_0 + \Delta t)$ as
\[\hat{u} = u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right),\]
where the implicit equation for $U_i$ is now
\[u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to $\hat{u}$ in the IMEX ARK method is straightforward:
\[\hat{u} = \textrm{DSS}\left(u_0 + \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right)\right).\]
Applying DSS to each stage $U_i$ is a bit trickier. Ideally, we would use the equation
\[\textrm{DSS}\left(\begin{aligned} & u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + \\ & \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) \end{aligned}\right) - U_i = 0,\]
since this would ensure that the implicit tendency $T_{\text{imp}}$ gets evaluated at a continuous stage $U_i$. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than $T_{\text{imp}}$, to an unknown quantity. So, we instead use the equation
\[\begin{aligned} \textrm{DSS}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
This equation is identical to the previous one only when $T_{\text{imp}}$ preserves the effects of DSS. That is to say, if evaluating $T_{\text{imp}}$ at a continuous stage $U_i$ produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute $U_i$ preserves the effects of DSS, which will usually be the case as long as $T_{\text{imp}}$ does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by $T_{\text{imp}}$. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute $U_i$ after applying the filter.
Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage $U_i$, but, unlike the actual tendencies $T_{\text{exp}}$ and $T_{\text{imp}}$, the effects of DSS on the previous stages $U_1, U_2, \ldots, U_{i - 1}$ are not accounted for when computing $U_i$. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation $F(u(t), t) = 0$ that can only be satisfied when $u(t)$ obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.
In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see [1]), which is a function $\textrm{lim}_{u(t)}$ that, when used with an appropriate tendency $T_{\text{lim}}(u(t), t)$ and a sufficiently small constant $C$, satisfies the inequalities
\[\begin{aligned} \textrm{min}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\geq \textrm{min}\bigl(u(t)\bigr) \text{ and} \\ \textrm{max}\biggl(\textrm{lim}_{u(t)}\bigl(u(t) + C T_{\text{lim}}(u(t), t)\bigr)\biggr) &\leq \textrm{max}\bigl(u(t)\bigr). \end{aligned}\]
In other words, applying the limiter to a state incremented by the limited tendency, $u(t) + C T_{\text{lim}}(u(t), t)$, ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, $u(t)$. Note that the process of incrementing a state in this way is used by the forward Euler method with $\Delta t = C$ and $T = T_{\text{lim}}$, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in $\textrm{lim}_{u(t)}$).
Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split $T_{\text{exp}}$ into two tendencies $T_{\text{exp}}$ and $T_{\text{lim}}$, to modify the equation for $\hat{u}$ to
\[\begin{aligned} \hat{u} ={} & \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{lim}}(U_i, t_0 + \Delta t \tilde{c}_i)\right) + \\ & \Delta t \sum_{i = 1}^s \left(\tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i)\right), \end{aligned}\]
and to modify the equation for $U_i$ to
\[\begin{aligned} \textrm{lim}_{u_0}\left(u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{lim}}(U_j, t_0 + \Delta t \tilde{c}_j)\right) + & \\ \Delta t \sum_{j = 1}^{i - 1} \left(\tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) + a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j)\right) + & \\ \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i &= 0. \end{aligned}\]
Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of $\textrm{lim}_{u_0}$ does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.
In order to use the limiter "more correctly", we constrain the ERK Butcher tableau coefficients to have the following form:
If all of the coefficients $\beta_1, \beta_2, \ldots, \beta_s$ are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.
Now, in order to simplify our notation, we will define $s + 1$ values $\tilde{U}_1, \tilde{U}_2, \ldots, \tilde{U}_{s + 1}$, where
\[\tilde{U}_i = \begin{cases} \displaystyle u_0 + \Delta t \sum_{j = 1}^{i - 1} \tilde{a}_{i,j} T_{\text{exp}}(U_j, t_0 + \Delta t \tilde{c}_j) & i < s + 1 \\ \displaystyle u_0 + \Delta t \sum_{i = 1}^s \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) & i = s + 1 \end{cases}.\]
This allows us to rewrite the IMEX ARK equation for $\hat{u}$ as
\[\hat{u} = \tilde{U}_{s + 1} + \Delta t \sum_{i = 1}^s b_i T_{\text{imp}}(U_i, t_0 + \Delta t c_i),\]
and to rewrite the equation for $U_i$ as
\[\tilde{U}_i + \Delta t \sum_{j = 1}^{i - 1} a_{i,j} T_{\text{imp}}(U_j, t_0 + \Delta t c_j) + \Delta t a_{i,i} T_{\text{imp}}(U_i, t_0 + \Delta t c_i) - U_i = 0.\]
If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express $\tilde{b}_i$ as
\[\tilde{b}_i = \begin{cases} \beta_s \tilde{a}_{s,i} & i < s \\ \beta_s & i = s \end{cases},\]
which means that
\[\begin{aligned} \tilde{U}_{s + 1} ={} & u_0 + \Delta t \sum_{i = 1}^{s - 1} \tilde{b}_i T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \tilde{b}_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & u_0 + \Delta t \beta_s \sum_{i = 1}^{s - 1} \tilde{a}_{s,i} T_{\text{exp}}(U_i, t_0 + \Delta t \tilde{c}_i) + \Delta t \beta_s T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s) = \\ & (1 - \beta_s) u_0 + \beta_s \left(\tilde{U}_s + \Delta t T_{\text{exp}}(U_s, t_0 + \Delta t \tilde{c}_s)\right). \end{aligned}\]
Since $\tilde{U}_1 = u_0$, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express $\tilde{U}_i$ as
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ (1 - \beta_{i - 1}) u_0 + \beta_{i - 1} \left(\tilde{U}_{i - 1} + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) & i > 1 \end{cases}.\]
To incorporate the use of a limiter into the IMEX SSPRK method, we split $T_{\text{exp}}$ into $T_{\text{exp}}$ and $T_{\text{lim}}$, and we modify the equation for $\tilde{U}_i$ to
\[\tilde{U}_i = \begin{cases} u_0 & i = 1 \\ \begin{aligned} & (1 - \beta_{i - 1}) u_0 +{} \\ & \quad\beta_{i - 1} \left(\textrm{lim}_{\tilde{U}_{i - 1}}\left(\tilde{U}_{i - 1} + \Delta t T_{\text{lim}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) + \Delta t T_{\text{exp}}(U_{i - 1}, t_0 + \Delta t \tilde{c}_{i - 1})\right) \end{aligned} & i > 1 \end{cases}.\]
In this equation, the limiter is being applied to a limited tendency evaluated at $U_{i - 1}$, but with $\tilde{U}_{i - 1}$ as the unincremented state. If there is no implicit tendency, so that $T_{\text{imp}}$ is always 0, then $U_{i - 1} = \tilde{U}_{i - 1}$, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.
The value of $U_i$ can be computed by running Newton's method with $f = f_i$ and $j = W_i$.
Note that "$W$" is used to denote the same quantity in OrdinaryDiffEq.jl.
1 More precisely, the local truncation error of the forward and backward Euler methods after a single timestep is $O\left((\Delta t)^2\right)$, which means that $|u(t_0 + \Delta t) - \hat{u}| < C (\Delta t)^2$ for all $\Delta t < D$, where $C$ and $D$ are some constants. On the other hand, the global truncation error after taking enough timesteps to go from $t_0$ to some $t_1 > t_0$ is $O(\Delta t)$. This is because there are $(t_1 - t_0) / \Delta t$ timesteps between $t_0$ and $t_1$, and, if each timestep has a local truncation error of $O\left((\Delta t)^2\right)$, then the error after $O\left((\Delta t)^{-1}\right)$ timesteps must be $O(\Delta t)$. In general, for a Runge-Kutta method (or ARK method) of order $p$, the local truncation error is $O\left((\Delta t)^{p + 1}\right)$, and the global truncation error is $O\left((\Delta t)^{p\vphantom{1}}\right)$.
2 By Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since $\textrm{lim}_{u_0}$ will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.
3 This is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store $u_0$; this is an example of a $2N^*$ method (see [2]). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to $s$ independent coefficients $\beta_i$ merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.
Settings
This document was generated with Documenter.jl version 0.27.25 on Wednesday 13 September 2023. Using Julia version 1.9.3.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the "chord method".
In addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
A boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).
The cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.
An UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.
An UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.
A mechanism for constraining which operations can be performed by an algorithm for solving ODEs.
For example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a "strong stability preserving" algorithm can only take linear combinations of "incremented states"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).
Indicates that an algorithm must be "strong stability preserving", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.
A wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.
The explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).
Constructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.
A wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.
Constructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.
Note that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).
An IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.
An IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.
Family of IMEX SSPRK algorithms parametrized by the value β from [12], Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in [11].
An IMEX ARK algorithm from [15] with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.
The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.
In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).
By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.
The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore
include("report_gen.jl")
┌ Warning: Order uncertainty too large for RK4 (ark_analytic)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
+┌ Warning: Order uncertainty too large for RK4 (ark_onewaycouple_mri)
+└ @ Main ~/work/ClimaTimeSteppers.jl/ClimaTimeSteppers.jl/docs/build/plotting_utils.jl:217
In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from "Optimization-based limiters for the spectral element method" by Guba et al. This involves running the horizontal_deformational_flow test case (from "A standard test case suite for two-dimensional linear transport on the sphere" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSPSSP333, but not when using the UnconstrainedARS343.
# This also runs with num_steps = 1000, but with larger under/overshoots; 4800
+# is the value used in the paper.
+limiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.DistributedODEAlgorithm)
import AbstractTrees as AT
+import InteractiveUtils as IU
+import ClimaTimeSteppers as CTS
+AT.children(x::Type) = IU.subtypes(x)
+AT.print_tree(CTS.AbstractAlgorithmName)
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
L. J. Wicker and W. C. Skamarock. A time-splitting scheme for the elastic equations incorporating second-order Runge–Kutta time differencing. Monthly Weather Review 126, 1992–1999 (1998).
D. J. Gardner, J. E. Guerra, F. P. Hamon, D. R. Reynolds, P. A. Ullrich and Woodward. Implicit–explicit (IMEX) Runge–Kutta methods for non-hydrostatic atmospheric models. Geoscientific Model Development 11, 1497–1515 (2018).
+
[12]
+
+
S. Conde, S. Gottlieb, Z. J. Grant and J. N. Shadid. Implicit and Implicit–Explicit Strong Stability Preserving Runge–Kutta Methods with High Linear Order. Journal of Scientific Computing 73, 667–-690 (2017).
This document was generated with Documenter.jl version 0.27.25 on Wednesday 13 September 2023. Using Julia version 1.9.3.
diff --git a/previews/PR203/search_index.js b/previews/PR203/search_index.js
new file mode 100644
index 000000000..7a51098d4
--- /dev/null
+++ b/previews/PR203/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"api/callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"api/callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"api/callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(\n f!,\n Δwt,\n comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false\n)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt; atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"api/callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps; atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"algorithm_formulations/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/#Standard-IMEX-ARK","page":"ODE Solvers","title":"Standard IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An ordinary differential equation (ODE) is an equation of the form","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracddtu(t) = T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where u(t) is called the state at time t, and T(u(t) t) is called the tendency of the state at time t.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The simplest method for numerically solving this equation with a finite timestep Delta t is the forward Euler method, in which the equation is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t) t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given the value of u_0 = u(t_0) at some time t_0, the approximation implies that u(t_0 + Delta t) approx hatu, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t T(u_0 t_0)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"An alternative approximation is given by the backward Euler method:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, u(t_0 + Delta t) approx hatu, where hatu is now the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unlike the forward Euler method, in which hatu is directly computed based on the known state u_0, the backward Euler method involves solving a root equation in order to obtain the value of hatu. So, the forward Euler method is called an explicit method, whereas the backward Euler method is called an implicit method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In general, T can be a complicated nonlinear function of u(t) and t, and it is usually not possible to solve the backward Euler method's implicit equation for hatu analytically. Instead, it is often necessary to use an iterative root-finding algorithm like Newton's method to solve for hatu. Although this is more computationally expensive than using the forward Euler method to directly obtain hatu from u_0, it is often necessary to deal with the problem of stiffness.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Roughly speaking, a tendency T is stiff when the forward Euler method requires a relatively small timestep Delta t to obtain a reasonably accurate solution, where \"relatively small\" means that it is smaller than one would expect based on the rate at which u(t) changes over time. When T is not stiff, a small timestep is only required when u(t) changes quickly with respect to t, and a larger timestep can be used when u(t) changes slowly. The backward Euler method is more stable than the forward Euler method, which means that it is usually able to take larger timesteps, especially when T is stiff.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"As a compromise between the simplicity of the forward Euler method and the stability of the backward Euler method, it is common to use the implicit-explicit (IMEX) Euler method. This involves splitting T into an explicit tendency T_textexp and an implicit tendency T_textimp, so that T(u(t) t) = T_textexp(u(t) t) + T_textimp(u(t) t), and making the approximation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"fracu(t + Delta t) - u(t)Delta t approx T_textexp(u(t) t) + T_textimp(u(t + Delta t) t + Delta t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"With this approximation, the implicit equation for hatu becomes","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t T_textexp(u_0 t_0) + Delta t T_textimp(hatu t_0 + Delta t) - hatu = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that T_textexp is evaluated explicitly at the known state u_0, while T_textimp is evaluated implicitly at the unknown state hatu.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Both the forward and backward Euler methods (and, by extension, the IMEX Euler method) are first-order methods, which means that the errors of their approximations are proportional to Delta t when Delta t is sufficiently close to 0.[1] In order to achieve a reasonable accuracy with fewer timesteps, it is common to use higher-order methods, where a method of order p will have an error that is proportional to (Delta t)^p for small values of Delta t. The simplest higher-order generalization of the forward and backward Euler methods is a Runge-Kutta method, in which there are s stages U_1 U_2 ldots U_s that satisfy","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[1]: \nMore precisely, the local truncation error of the forward and backward Euler methods after a single timestep is Oleft((Delta t)^2right), which means that u(t_0 + Delta t) - hatu C (Delta t)^2 for all Delta t D, where C and D are some constants. On the other hand, the global truncation error after taking enough timesteps to go from t_0 to some t_1 t_0 is O(Delta t). This is because there are (t_1 - t_0) Delta t timesteps between t_0 and t_1, and, if each timestep has a local truncation error of Oleft((Delta t)^2right), then the error after Oleft((Delta t)^-1right) timesteps must be O(Delta t). In general, for a Runge-Kutta method (or ARK method) of order p, the local truncation error is Oleft((Delta t)^p + 1right), and the global truncation error is Oleft((Delta t)^pvphantom1right).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^s a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and u(t_0 + Delta t) is approximated as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s b_i T(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The coefficients a_ij, b_i, and c_i of a Runge-Kutta method can be summarized in a Butcher tableau:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c c_1 a_11 a_12 cdots a_1s - 1 a_1s c_2 a_21 a_22 cdots a_2s - 1 a_2s c_3 a_31 a_32 cdots a_3s - 1 a_3s vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since solving a system of s coupled equations for the stages U_i is usually impractical, many of the a_ij coefficients are set to 0 in commonly used Runge-Kutta methods. When a_ij = 0 for all j geq i, the equation for U_i simplifies to the explicit formula","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"U_i = u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This is called an explicit Runge-Kutta (ERK) method. When a_ij = 0 for all j i, the implicit equation for U_i becomes uncoupled from the equations for the other stages, and it can be rewritten as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 a_ij T(U_j t_0 + Delta t c_j) + Delta t a_ii T(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since the only unknown tendency in this equation comes from the diagonal coefficient a_ii, this is called a diagonally implicit Runge-Kutta (DIRK) method. There are many different categories of DIRK methods, such as explicit first stage DIRK (EDIRK), where a_11 = 0, singly DIRK (SDIRK), where a_11 = a_22 = ldots = a_ss = gamma for some constant gamma, and ESDIRK, where a_11 = 0 and a_22 = ldots = a_ss = gamma.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Just as the forward and backward Euler methods can be combined into the IMEX Euler method, two Runge-Kutta methods can be combined into an additive Runge-Kutta (ARK) method. If the first method is explicit and the second is implicit, the result is an IMEX ARK method. We will only be considering IMEX ARK methods where the implicit part is DIRK. If the DIRK method has coefficients a_ij, b_i, and c_i, and the ERK method has coefficients tildea_ij, tildeb_i, and tildec_i, the IMEX ARK method approximates u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where the implicit equation for U_i is now","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-DSS","page":"ODE Solvers","title":"Adding DSS","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"It is often necessary to filter the state so that it satisfies some particular constraint before it is used to evaluate a tendency. In our case, the state is a collection of values defined across a spatially discretized domain. When we use a continuous Galerkin (CG) spectral element discretization, we must ensure that the state is continuous across element boundaries before we use it to compute any tendency. We can turn any state that is discontinuous across element boundaries into a continuous one by applying a direct stiffness summation (DSS) to it. Applying DSS to hatu in the IMEX ARK method is straightforward:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(u_0 + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Applying DSS to each stage U_i is a bit trickier. Ideally, we would use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) endalignedright) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"since this would ensure that the implicit tendency T_textimp gets evaluated at a continuous stage U_i. However, this equation is more challenging to solve than the original one, since it involves applying DSS, which is usually a more complicated function than T_textimp, to an unknown quantity. So, we instead use the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmDSSleft(u_0 + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This equation is identical to the previous one only when T_textimp preserves the effects of DSS. That is to say, if evaluating T_textimp at a continuous stage U_i produces a continuous tendency, then it is not necessary to apply DSS after adding this tendency to a continuous quantity. This also assumes that the root-finding algorithm used to compute U_i preserves the effects of DSS, which will usually be the case as long as T_textimp does so. In general, one could replace DSS with a filter that enforces some other constraint, as long as that constraint is preserved by T_textimp. The constraint must also be preserved by addition and by multiplication with a constant, which are the only other operations used to compute U_i after applying the filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that this method of enforcing a constraint is not mathematically rigorous, as it does not necessarily maintain the convergence properties of the IMEX ARK method. This is because DSS effectively acts like a tendency on each stage U_i, but, unlike the actual tendencies T_textexp and T_textimp, the effects of DSS on the previous stages U_1 U_2 ldots U_i - 1 are not accounted for when computing U_i. The proper way to enforce a constraint would be to extend the ODE to a differential-algebraic equation (DAE) by adding an algebraic equation F(u(t) t) = 0 that can only be satisfied when u(t) obeys the constraint, and then solving the DAE using an appropriate numerical method. However, this route would be significantly more computationally expensive than our method. Moreover, we have observed that the effects of DSS are sufficiently small to not noticeably disrupt the convergence of IMEX ARK methods in our test cases, though this will not necessarily be the case if DSS is replaced with another filter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Adding-a-Limiter","page":"ODE Solvers","title":"Adding a Limiter","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition to filtering the state, it is often necessary to filter part of the tendency, but in a way that depends on the state to which the tendency is being added. In our case, because we use a spectral element discretization, part of the explicit tendency can add spurious oscillations to each stage. We can limit these oscillations by using a monotonicity-preserving limiter (see [1]), which is a function textrmlim_u(t) that, when used with an appropriate tendency T_textlim(u(t) t) and a sufficiently small constant C, satisfies the inequalities","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmminbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) geq textrmminbigl(u(t)bigr) text and textrmmaxbiggl(textrmlim_u(t)bigl(u(t) + C T_textlim(u(t) t)bigr)biggr) leq textrmmaxbigl(u(t)bigr) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In other words, applying the limiter to a state incremented by the limited tendency, u(t) + C T_textlim(u(t) t), ensures that the extrema of the incremented state do not exceed the extrema of the unincremented state, u(t). Note that the process of incrementing a state in this way is used by the forward Euler method with Delta t = C and T = T_textlim, which is why it is called an Euler step. Since spurious oscillations usually cause the extrema of the state to grow, this is an effective mechanism for eliminating such oscillations. Note that the limiter can only preserve monotonicity by comparing the incremented state to the unincremented state, which means that the effects of the limiter are a function of the unincremented state (hence the subscript in textrmlim_u(t)).","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Unfortunately, there is no mathematically correct way to incorporate the use of a limiter into a general IMEX ARK method. The most straightforward approach is to split T_textexp into two tendencies T_textexp and T_textlim, to modify the equation for hatu to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned hatu = textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to modify the equation for U_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0 endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Not only does this approach not maintain the convergence properties of the IMEX ARK method (for the same reason as DSS above),[2] but it also does not even use the limiter in a way that allows it to preserve monotonicity. That is, the argument of textrmlim_u_0 does not have the form needed to satisfy the min and max constraints given above, since it involves evaluating the limited tendency at states that are not the unincremented state. As luck would have it, we have observed that the limiter, even when used in such an incorrect manner, is still able to substantially reduce spurious oscillations in our test cases, though it is not able to perform as well as it would if it were used correctly.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[2]: \nBy Godunov's theorem, no monotonicity-preserving linear numerical method can have an order greater than 1. Since textrmlim_u_0 will usually be a nonlinear function, this is not a linear numerical method. However, it is a rough approximation of the unmodified ARK method, so it is likely that Godunov's theorem will still apply; i.e., we do not expect to observe an order greater than 1 when using a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In order to use the limiter \"more correctly\", we constrain the ERK Butcher tableau coefficients to have the following form:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If all of the coefficients beta_1 beta_2 ldots beta_s are nonnegative, and if the resulting ERK method converges, it is called a strong stability preserving Runge-Kutta (SSPRK) method.[3] Moreover, if the ERK method is SSPRK, then the overall IMEX ARK method is called an IMEX SSPRK method.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"[3]: \nThis is really a low-storage SSPRK method that only requires two registers for storing states, using one of the registers to store u_0; this is an example of a 2N^* method (see [2]). A general SSPRK method has just as many independent coefficients as a general ERK method, though its coefficients are used somewhat differently, in a way that makes them more amenable to limiters. We restrict ourselves to s independent coefficients beta_i merely for the sake of simplicity. In the future, we might want to generalize to arbitrary SSPRK methods.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Now, in order to simplify our notation, we will define s + 1 values tildeU_1 tildeU_2 ldots tildeU_s + 1, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases displaystyle u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) i s + 1 displaystyle u_0 + Delta t sum_i = 1^s tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) i = s + 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"This allows us to rewrite the IMEX ARK equation for hatu as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and to rewrite the equation for U_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"If we constrain the IMEX ARK method to an IMEX SSPRK method, we can express tildeb_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeb_i = begincases beta_s tildea_si i s beta_s i = s endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_s + 1 = u_0 + Delta t sum_i = 1^s - 1 tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + Delta t tildeb_s T_textexp(U_s t_0 + Delta t tildec_s) = u_0 + Delta t beta_s sum_i = 1^s - 1 tildea_si T_textexp(U_i t_0 + Delta t tildec_i) + Delta t beta_s T_textexp(U_s t_0 + Delta t tildec_s) = (1 - beta_s) u_0 + beta_s left(tildeU_s + Delta t T_textexp(U_s t_0 + Delta t tildec_s)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In addition, for all i 1,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildea_ij = begincases beta_i - 1 tildea_i - 1j j i - 1 beta_i - 1 j = i - 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"which means that","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginaligned tildeU_i = u_0 + Delta t sum_j = 1^i - 2 tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + Delta t tildea_ii - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = u_0 + Delta t beta_i - 1 sum_j = 1^i - 2 tildea_i - 1j T_textexp(U_j t_0 + Delta t tildec_j) + Delta t beta_i - 1 T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1) = (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Since tildeU_1 = u_0, constraining the IMEX ARK method to an IMEX SSPRK method allows us to express tildeU_i as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 (1 - beta_i - 1) u_0 + beta_i - 1 left(tildeU_i - 1 + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"To incorporate the use of a limiter into the IMEX SSPRK method, we split T_textexp into T_textexp and T_textlim, and we modify the equation for tildeU_i to","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this equation, the limiter is being applied to a limited tendency evaluated at U_i - 1, but with tildeU_i - 1 as the unincremented state. If there is no implicit tendency, so that T_textimp is always 0, then U_i - 1 = tildeU_i - 1, and the limiter is able to properly preserve monotonicity. On the other hand, if there is an implicit tendency, then the limiter will not necessarily preserve monotonicity. That is, the limiter is guaranteed to function properly when the limited tendency is used in a sequence of Euler steps.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Summary","page":"ODE Solvers","title":"Summary","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"We will now summarize our IMEX methods when using both DSS and a limiter.","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-ARK","page":"ODE Solvers","title":"IMEX ARK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our general IMEX ARK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 tildea_21 0 cdots 0 0 tildec_3 tildea_31 tildea_32 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s tildea_s1 tildea_s2 cdots tildea_ss - 1 0 hline tildeb_1 tildeb_2 cdots tildeb_s - 1 tildeb_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_i = 1^s tildeb_i T_textlim(U_i t_0 + Delta t tildec_i)right) + Delta t sum_i = 1^s left(tildeb_i T_textexp(U_i t_0 + Delta t tildec_i) + b_i T_textimp(U_i t_0 + Delta t c_i)right) endalignedright)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(beginaligned textrmlim_u_0left(u_0 + Delta t sum_j = 1^i - 1 tildea_ij T_textlim(U_j t_0 + Delta t tildec_j)right) + Delta t sum_j = 1^i - 1 left(tildea_ij T_textexp(U_j t_0 + Delta t tildec_j) + a_ij T_textimp(U_j t_0 + Delta t c_j)right) endalignedright) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/#IMEX-SSPRK","page":"ODE Solvers","title":"IMEX SSPRK","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Our IMEX SSPRK method is defined by two Butcher tableaus:","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"beginarraycc c c c c tildec_1 0 0 cdots 0 0 tildec_2 beta_1 0 cdots 0 0 tildec_3 beta_1 beta_2 beta_2 cdots 0 0 vdots vdots vdots ddots vdots vdots tildec_s beta_1 beta_2 ldots beta_s - 1 beta_2 ldots beta_s - 1 cdots beta_s - 1 0 hline beta_1 beta_2 ldots beta_s - 1 beta_s beta_2 ldots beta_s - 1 beta_s cdots beta_s - 1 beta_s beta_s endarray text and beginarraycc c c c c c_1 a_11 0 cdots 0 0 c_2 a_21 a_22 cdots 0 0 c_3 a_31 a_32 cdots 0 0 vdots vdots vdots ddots vdots vdots c_s a_s1 a_s2 cdots a_ss - 1 a_ss hline b_1 b_2 cdots b_s - 1 b_s endarray","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Given u_0 = u(t_0), it approximates the value of u(t_0 + Delta t) as","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"hatu = textrmDSSleft(tildeU_s + 1 + Delta t sum_i = 1^s b_i T_textimp(U_i t_0 + Delta t c_i)right)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where U_i is the solution to the equation","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"textrmDSSleft(tildeU_i + Delta t sum_j = 1^i - 1 a_ij T_textimp(U_j t_0 + Delta t c_j)right) + Delta t a_ii T_textimp(U_i t_0 + Delta t c_i) - U_i = 0","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"and where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"tildeU_i = begincases u_0 i = 1 beginaligned (1 - beta_i - 1) u_0 + quadbeta_i - 1 left(textrmlim_tildeU_i - 1left(tildeU_i - 1 + Delta t T_textlim(U_i - 1 t_0 + Delta t tildec_i - 1)right) + Delta t T_textexp(U_i - 1 t_0 + Delta t tildec_i - 1)right) endaligned i 1 endcases","category":"page"},{"location":"algorithm_formulations/ode_solvers/#Running-Newton's-Method","page":"ODE Solvers","title":"Running Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Every implicit equation for U_i has the form f_i(U_i) = 0, where","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"f_i(x) = R_i + Delta t a_ii T_textimp(x t_0 + Delta t c_i) - x","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"In this function, R_i, Delta t a_ii, and t_0 + Delta t c_i are all quantities that do not depend on x. The Jacobian of this function is","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"W_i(x) = fracddxf_i(x) = Delta t a_ii J_textimp(x t_0 + Delta t c_i) - 1","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"where J_textimp is the Jacobian of the implicit tendency,","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"J_textimp(x t) = fracpartialpartial xT_textimp(x t)","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"The value of U_i can be computed by running Newton's method with f = f_i and j = W_i.","category":"page"},{"location":"algorithm_formulations/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Note that \"W\" is used to denote the same quantity in OrdinaryDiffEq.jl.","category":"page"},{"location":"test_problems/#Test-problems","page":"Test problems","title":"Test problems","text":"","category":"section"},{"location":"test_problems/","page":"Test problems","title":"Test problems","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"algorithm_formulations/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"TODO: fill out","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Runge-Kutta","page":"Old MRRK Formulations","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"[3] defines the following method.","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"algorithm_formulations/mrrk/#Low-storage","page":"Old MRRK Formulations","title":"Low-storage","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"where","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"algorithm_formulations/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Old MRRK Formulations","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"Multirate Infinitesimal Step (MIS) methods ([4], [5])","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"algorithm_formulations/mrrk/#Wicker-Skamarock","page":"Old MRRK Formulations","title":"Wicker Skamarock","text":"","category":"section"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"[6] and [7] define RK2 and RK3 multirate schemes:","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"algorithm_formulations/mrrk/","page":"Old MRRK Formulations","title":"Old MRRK Formulations","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"dev/report_gen/#Verifying-Correctness","page":"Report generator","title":"Verifying Correctness","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The IMEXAlgorithm supports problems that specify any combination of the following: an implicit tendency T_imp!, an explicit tendency T_exp!, a limited tendency T_lim!, a function dss! that applies a direct stiffness summation, and a function lim! that applies a monotonicity-preserving limiter.","category":"page"},{"location":"dev/report_gen/#Convergence-without-a-Limiter","page":"Report generator","title":"Convergence without a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms without a limiter, we compute their convergence orders for a variety of test cases. For each case, we estimate the convergence order of the algorithm over a range of stable timesteps, ensuring that the estimate computed_order ± order_uncertainty satisfies |computed_order - predicted_order| ≤ order_uncertainty and order_uncertainty ≤ predicted_order / 10. We also generate a plot that shows each algorithm's convergence as the timestep is reduced, along with plots that show the norms of each algorithm's solution and error over time (for some stable timestep). In addition, we verify that SSP algorithms produce the same results (up to floating-point roundoff error) when run in Unconstrained mode (at least, when run without a limiter).","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"By Godunov's theorem, the use of a monotonicity-preserving limiter reduces the convergence order of any algorithm to 1, so we do not include any test cases that use T_lim! and lim!.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"The test cases we use for this analysis are: - ark_analytic, which uses a nonlinear T_exp! and a linear T_imp! - ark_analytic_sys and ark_onewaycouple_mri, which use a linear T_imp! - ark_analytic_nonlin, which uses a nonlinear T_imp! - 1d_heat_equation and 2d_heat_equation, which use a nonlinear T_exp! and dss!, where the spatial discretization is implemented using ClimaCore","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"include(\"report_gen.jl\")","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"(Image: ) (Image: ) (Image: ) (Image: ) (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#Errors-with-a-Limiter","page":"Report generator","title":"Errors with a Limiter","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"In order to verify the correctness of our algorithms with a limiter, we recreate Table 1 from \"Optimization-based limiters for the spectral element method\" by Guba et al. This involves running the horizontal_deformational_flow test case (from \"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.) with and without a limiter, and also with and without hyperdiffusion. This test case uses a limited tendency T_lim! (which consists of advection and, optionally, hyperdiffusion), along with dss! and lim!. The spatial discretization is implemented using ClimaCore. Since this analysis is relatively expensive to run, we only check the results for SSP333 and ARS343. Note that it is possible to limit undershoots and overshoots to 0 (up to floating-point roundoff error) when using the SSP SSP333, but not when using the Unconstrained ARS343.","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"using ClimaTimeSteppers # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"rapplypatch.jl\")) # hide\nENV[\"GKSwstype\"] = \"nul\" # hide\ninclude(joinpath(@__DIR__, \"..\", \"plotting_utils.jl\")) # hide\ninclude(joinpath(pkgdir(ClimaTimeSteppers), \"test\", \"problems.jl\")) # hide\n\n# This also runs with num_steps = 1000, but with larger under/overshoots; 4800\n# is the value used in the paper.\nlimiter_summary(Float64, [SSP333(), ARS343()], horizontal_deformational_flow_test, 4800)","category":"page"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Plots of the tracer specific humidities that were used to compute this table are shown below. (Image: ) (Image: )","category":"page"},{"location":"dev/report_gen/#References","page":"Report generator","title":"References","text":"","category":"section"},{"location":"dev/report_gen/","page":"Report generator","title":"Report generator","text":"Example Programs for ARK ode (SUNDIALS)\n\"Optimization-based limiters for the spectral element method\" by Guba et al.\n\"A standard test case suite for two-dimensional linear transport on the sphere\" by Lauritzen et al.","category":"page"},{"location":"api/ode_solvers/#ODE-Solvers","page":"ODE Solvers","title":"ODE Solvers","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/ode_solvers/#Interface","page":"ODE Solvers","title":"Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"AbstractAlgorithmConstraint\nUnconstrained\nSSP\nIMEXTableau\nIMEXAlgorithm\nExplicitTableau\nExplicitAlgorithm","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.AbstractAlgorithmConstraint","page":"ODE Solvers","title":"ClimaTimeSteppers.AbstractAlgorithmConstraint","text":"AbstractAlgorithmConstraint\n\nA mechanism for constraining which operations can be performed by an algorithm for solving ODEs.\n\nFor example, an unconstrained algorithm might compute a Runge-Kutta stage by taking linear combinations of tendencies; i.e., by adding quantities of the form dt * tendency(state). On the other hand, a \"strong stability preserving\" algorithm can only take linear combinations of \"incremented states\"; i.e., it only adds quantities of the form state + dt * coefficient * tendency(state).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Unconstrained","page":"ODE Solvers","title":"ClimaTimeSteppers.Unconstrained","text":"Unconstrained\n\nIndicates that an algorithm may perform any supported operations.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP","text":"SSP\n\nIndicates that an algorithm must be \"strong stability preserving\", which makes it easier to guarantee that the algorithm will preserve monotonicity properties satisfied by the initial state. For example, this ensures that the algorithm will be able to use limiters in a mathematically consistent way.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXTableau","text":"IMEXTableau(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nA wrapper for an IMEX Butcher tableau (or, more accurately, a pair of Butcher tableaus, one for explicit tendencies and the other for implicit tendencies). Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that it is internally consistent.\n\nThe explicit tableau must be strictly lower triangular, and the implicit tableau must be lower triangular (only DIRK algorithms are currently supported).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMEXAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.IMEXAlgorithm","text":"IMEXAlgorithm(tableau, newtons_method, [constraint])\nIMEXAlgorithm(name, newtons_method, [constraint])\n\nConstructs an IMEX algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any IMEXTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an IMEXARKAlgorithmName.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitTableau","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitTableau","text":"ExplicitTableau(; a, b, c)\n\nA wrapper for an explicit Butcher tableau. Only a is a required argument; the default value for b assumes that the algorithm is FSAL (first same as last), and the default value for c assumes that it is internally consistent. The matrix a must be strictly lower triangular.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ExplicitAlgorithm","page":"ODE Solvers","title":"ClimaTimeSteppers.ExplicitAlgorithm","text":"ExplicitAlgorithm(tableau, [constraint])\nExplicitAlgorithm(name, [constraint])\n\nConstructs an explicit algorithm for solving ODEs, with an optional name and constraint. The first constructor accepts any ExplicitTableau and an optional constraint, leaving the algorithm unnamed. The second constructor automatically determines the tableau and the default constraint from the algorithm name, which must be an ERKAlgorithmName.\n\nNote that using an ExplicitAlgorithm is merely a shorthand for using an IMEXAlgorithm with the same tableau for explicit and implicit tendencies (and without Newton's method).\n\n\n\n\n\n","category":"function"},{"location":"api/ode_solvers/#IMEX-Algorithm-Names","page":"ODE Solvers","title":"IMEX Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ARS111\nARS121\nARS122\nARS233\nARS232\nARS222\nARS343\nARS443\nIMKG232a\nIMKG232b\nIMKG242a\nIMKG242b\nIMKG243a\nIMKG252a\nIMKG252b\nIMKG253a\nIMKG253b\nIMKG254a\nIMKG254b\nIMKG254c\nIMKG342a\nIMKG343a\nSSP222\nSSP322\nSSP332\nSSP333\nSSP433\nDBM453\nHOMMEM1\nARK2GKC\nARK437L2SA1\nARK548L2SA2","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS111","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS111","text":"ARS111\n\nAn IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 1 explicit stage and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEuler.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS121","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS121","text":"ARS121\n\nAn IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 2 explicit stages, and 1st order accuracy. Also called IMEX Euler or forward-backward Euler; equivalent to OrdinaryDiffEq.IMEXEulerARK.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS122","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS122","text":"ARS122\n\nAn IMEX ARK algorithm from [8], section 2, with 1 implicit stage, 2 explicit stages, and 2nd order accuracy. Also called IMEX midpoint.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS233","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS233","text":"ARS233\n\nAn IMEX ARK algorithm from [8], section 2, with 2 implicit stages, 3 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS232","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS232","text":"ARS232\n\nAn IMEX ARK algorithm from [8], section 2, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS222","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS222","text":"ARS222\n\nAn IMEX ARK algorithm from [8], section 2, with 2 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS343","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS343","text":"ARS343\n\nAn IMEX ARK algorithm from [8], section 2, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARS443","page":"ODE Solvers","title":"ClimaTimeSteppers.ARS443","text":"ARS443\n\nAn IMEX ARK algorithm from [8], section 2, with 4 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232a","text":"IMKG232a\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG232b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG232b","text":"IMKG232b\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 3 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242a","text":"IMKG242a\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG242b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG242b","text":"IMKG242b\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG243a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG243a","text":"IMKG243a\n\nAn IMEX ARK algorithm from [9], Table 3, with 3 implicit stages, 4 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252a","text":"IMKG252a\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG252b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG252b","text":"IMKG252b\n\nAn IMEX ARK algorithm from [9], Table 3, with 2 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253a","text":"IMKG253a\n\nAn IMEX ARK algorithm from [9], Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG253b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG253b","text":"IMKG253b\n\nAn IMEX ARK algorithm from [9], Table 3, with 3 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254a","text":"IMKG254a\n\nAn IMEX ARK algorithm from [9], Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254b","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254b","text":"IMKG254b\n\nAn IMEX ARK algorithm from [9], Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG254c","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG254c","text":"IMKG254c\n\nAn IMEX ARK algorithm from [9], Table 3, with 4 implicit stages, 5 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG342a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG342a","text":"IMKG342a\n\nAn IMEX ARK algorithm from [9], Table 4, with 2 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.IMKG343a","page":"ODE Solvers","title":"ClimaTimeSteppers.IMKG343a","text":"IMKG343a\n\nAn IMEX ARK algorithm from [9], Table 4, with 3 implicit stages, 4 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP222","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP222","text":"SSP222\n\nAn IMEX SSPRK algorithm from [10], with 2 implicit stages, 2 explicit stages, and 2nd order accuracy. Also called SSP2(222) in [11].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP322","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP322","text":"SSP322\n\nAn IMEX SSPRK algorithm from [10], with 3 implicit stages, 2 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP332","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP332","text":"SSP332\n\nAn IMEX SSPRK algorithm from [10], with 3 implicit stages, 3 explicit stages, and 2nd order accuracy. Also called SSP2(332)a in [11].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP333","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP333","text":"SSP333(; β = 1/2 + √3/6)\n\nFamily of IMEX SSPRK algorithms parametrized by the value β from [12], Section 3.2, with 3 implicit stages, 3 explicit stages, and 3rd order accuracy. The default value of β results in an SDIRK algorithm, which is also called SSP3(333)c in [11].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP433","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP433","text":"SSP433\n\nAn IMEX SSPRK algorithm from [10], with 4 implicit stages, 3 explicit stages, and 3rd order accuracy. Also called SSP3(433) in [11].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.DBM453","page":"ODE Solvers","title":"ClimaTimeSteppers.DBM453","text":"DBM453\n\nAn IMEX ARK algorithm from [13], Appendix A, with 4 implicit stages, 5 explicit stages, and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.HOMMEM1","page":"ODE Solvers","title":"ClimaTimeSteppers.HOMMEM1","text":"HOMMEM1\n\nAn IMEX ARK algorithm from [14], section 4.1, with 5 implicit stages, 6 explicit stages, and 2nd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK2GKC","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK2GKC","text":"ARK2GKC(; paper_version = false)\n\nAn IMEX ARK algorithm from [15] with 2 implicit stages, 3 explicit stages, and 2nd order accuracy. If paper_version = true, the algorithm uses coefficients from the paper. Otherwise, it uses coefficients that make it more stable but less accurate.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK437L2SA1","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK437L2SA1","text":"ARK437L2SA1\n\nAn IMEX ARK algorithm from [16], Table 8, with 6 implicit stages, 7 explicit stages, and 4th order accuracy. Written as ARK4(3)7L[2]SA₁ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ARK548L2SA2","page":"ODE Solvers","title":"ClimaTimeSteppers.ARK548L2SA2","text":"ARK548L2SA2\n\nAn IMEX ARK algorithm from [16], Table 8, with 7 implicit stages, 8 explicit stages, and 5th order accuracy. Written as ARK5(4)8L[2]SA₂ in the paper.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Explicit-Algorithm-Names","page":"ODE Solvers","title":"Explicit Algorithm Names","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"SSP22Heuns\nSSP33ShuOsher\nRK4","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP22Heuns","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP22Heuns","text":"SSP22Heuns\n\nAn SSPRK algorithm from [17], with 2 stages and 2nd order accuracy. Also called Heun's method ([18]).\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.SSP33ShuOsher","page":"ODE Solvers","title":"ClimaTimeSteppers.SSP33ShuOsher","text":"SSP33ShuOsher\n\nAn SSPRK algorithm from [17], with 3 stages and 3rd order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.RK4","page":"ODE Solvers","title":"ClimaTimeSteppers.RK4","text":"RK4\n\nThe RK4 algorithm from [19], a Runge-Kutta method with 4 stages and 4th order accuracy.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-LSRK-Interface","page":"ODE Solvers","title":"Old LSRK Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"ForwardEulerODEFunction\nLowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"ODE Solvers","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"ODE Solvers","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of [20].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of [21] with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.LSRKEulerMethod","page":"ODE Solvers","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#Old-Multirate-Interface","page":"ODE Solvers","title":"Old Multirate Interface","text":"","category":"section"},{"location":"api/ode_solvers/","page":"ODE Solvers","title":"ODE Solvers","text":"Multirate\nMultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\nWickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"api/ode_solvers/#ClimaTimeSteppers.Multirate","page":"ODE Solvers","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"ODE Solvers","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of [4] and [5].\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS2","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS3C","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.MIS4a","page":"ODE Solvers","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISA","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.TVDMISB","page":"ODE Solvers","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of [5].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"ODE Solvers","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in [6] and [7], which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK2","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of [6].\n\n\n\n\n\n","category":"type"},{"location":"api/ode_solvers/#ClimaTimeSteppers.WSRK3","page":"ODE Solvers","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of [7].\n\n\n\n\n\n","category":"type"},{"location":"dev/types/#Types","page":"Types","title":"Types","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"In this section, we print out the type hierarchies of some classes via code snippets.","category":"page"},{"location":"dev/types/#Algorithms","page":"Types","title":"Algorithms","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.DistributedODEAlgorithm)","category":"page"},{"location":"dev/types/#Tableaus","page":"Types","title":"Tableaus","text":"","category":"section"},{"location":"dev/types/","page":"Types","title":"Types","text":"import AbstractTrees as AT\nimport InteractiveUtils as IU\nimport ClimaTimeSteppers as CTS\nAT.children(x::Type) = IU.subtypes(x)\nAT.print_tree(CTS.AbstractAlgorithmName)","category":"page"},{"location":"test_problems/diffusion_2d/#D-diffusion-problem","page":"2D diffusion problem","title":"2D diffusion problem","text":"","category":"section"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"TODO: cleanup","category":"page"},{"location":"test_problems/diffusion_2d/","page":"2D diffusion problem","title":"2D diffusion problem","text":"Due to conservation of (heat) energy, we know that\n c * ρ * ∂u/∂t = k * Δu + q,\nwhere u is the temperature (K), c is the specific heat capacity (J/kg/K), ρ is\nthe density (kg/m^3), k is the thermal conductivity (W/m/K), and q is the rate\nat which heat energy is added/removed (W/m^3).\nWe can simplify this PDE to\n ∂u/∂t = α * Δu + f,\nwhere α = k/c/ρ is the thermal diffusivity (m^2/s) and f = q/c/ρ is the rate at\nwhich heat energy is added/removed in units of temperature (K/s).\nWe will solve this PDE for u(x, y, t) over the domain (x, y) ∈ [0, l] × [0, l]\nand t ≥ 0. For simplicity, we will use periodic boundary conditions:\n u(0, y, t) = u(l, y, t),\n u(x, 0, t) = u(x, l, t),\n ∇u(0, y, t) = ∇u(l, y, t), and\n ∇u(x, 0, t) = ∇u(x, l, t).\nAlso, for simplicity, we will assume that α is a constant.\nSuppose that\n f = 0 and\n u(x, y, 0) = u₀(x, y).\nThe general solution to the PDE (obtained with separation of variables) is then\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ), where\n φᶜᶜₙₘ(x, y) = cos(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φᶜˢₙₘ(x, y) = cos(2 * π * n * x / l) * sin(2 * π * m * y / l),\n φˢᶜₙₘ(x, y) = sin(2 * π * n * x / l) * cos(2 * π * m * y / l),\n φˢˢₙₘ(x, y) = sin(2 * π * n * x / l) * sin(2 * π * m * y / l), and\n λₙₘ = (2 * π / l)^2 * (n^2 + m^2) * α.\nNote that the inner product of two functions g(x, y) and h(x, y) is defined as\n ⟨g(x, y), h(x, y)⟩ = ∫_0^l ∫_0^l g(x, y) h(x, y) dx dy.\nWhen n = 0 or m = 0, some of the inner product denominators above are 0, but\nthis doesn't actually matter because the corresponding numerators are also 0 and\nthose terms can just be ignored.\nSo, the solution operator for the homogeneous PDE (with f = 0) is\n F(u₀)(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n φᶜᶜₙₘ(x, y) * ⟨φᶜᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜᶜₙₘ(x, y), φᶜᶜₙₘ(x, y)⟩ +\n φᶜˢₙₘ(x, y) * ⟨φᶜˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φᶜˢₙₘ(x, y), φᶜˢₙₘ(x, y)⟩ +\n φˢᶜₙₘ(x, y) * ⟨φˢᶜₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢᶜₙₘ(x, y), φˢᶜₙₘ(x, y)⟩ +\n φˢˢₙₘ(x, y) * ⟨φˢˢₙₘ(x, y), u₀(x, y)⟩ / ⟨φˢˢₙₘ(x, y), φˢˢₙₘ(x, y)⟩\n ).\nWe can express the initial condition of our PDE using in terms of its Fourier\nseries as\n u₀(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nNow, consider the inhomogeneous PDE for which\n f(x, y, t) = f̂(t)(x, y) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λ′ₙₘ * t) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\n(Note that, if we allow the time-dependence to have a form that is not\nexponential, the resulting solution will contain non-elementary integrals.)\nDuhamel's formula tells us that the solution to the inhomogeneous PDE is\n u(x, y, t) = F(u₀)(x, y, t) + ∫_0^t F(f̂(τ))(x, y, t - τ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∫_0^t ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λ′ₙₘ * τ - λₙₘ * (t - τ)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n )\n ) dτ =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ (\n exp(-λₙₘ * t) / (λₙₘ - λ′ₙₘ) * (exp((λₙₘ - λ′ₙₘ) * t) - 1)\n ) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nIf we let λ′ₙₘ = λₙₘ + Δλₙₘ, this simplifies to\n u(x, y, t) =\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) * (\n u₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n u₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n u₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n u₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ) +\n ∑_{n = 0}^∞ ∑_{m = 0}^∞ exp(-λₙₘ * t) / Δλₙₘ * (1 - exp(-Δλₙₘ * t)) * (\n f₀ᶜᶜₙₘ * φᶜᶜₙₘ(x, y) +\n f₀ᶜˢₙₘ * φᶜˢₙₘ(x, y) +\n f₀ˢᶜₙₘ * φˢᶜₙₘ(x, y) +\n f₀ˢˢₙₘ * φˢˢₙₘ(x, y)\n ).\nFor the test case below, we will only use the φˢˢₙₘ eigenfunction for specific\nvalues of n and m. In other words, we will pick some constants n, m, u₀, f₀, and\nΔλ, and we will set\n u(x, y, 0) = u₀ * φˢˢₙₘ(x, y) and\n f(x, y, t) = f₀ * exp(-(λₙₘ + Δλ) * t) * φˢˢₙₘ(x, y).\nWe should then end up with the solution\n u(x, y, t) =\n (u₀ + f₀ / Δλ * (1 - exp(-Δλ * t))) * exp(-λₙₘ * t) * φˢˢₙₘ(x, y).\nIn addition, we will use nondimensionalization to replace our variables with\n x̂ = x / l,\n ŷ = y / l,\n t̂ = t / (l^2 / α),\n û(x̂, ŷ, t̂) = u(x, y, t) / u₀,\n f̂(x̂, ŷ, t̂) = f(x, y, t) / (u₀ / (l^2 / α)).\nNote that this converts the time t into the \"Fourier number\" α * t / l^2.\nWe will then define the nondimensionalized constants\n λ̂ₙₘ = λₙₘ * l^2 / α = (2 * π)^2 * (n^2 + m^2),\n Δλ̂ = Δλ * l^2 / α, and\n f̂₀ = f₀ / (u₀ / (l^2 / α))\nWe will also rewrite the eigenfunction in terms of the new variables as\n φ̂ˢˢₙₘ(x̂, ŷ) = φˢˢₙₘ(x̂ * l, ŷ * l) = sin(2 * π * n * x̂) * sin(2 * π * m * ŷ).\nOur simplified PDE then becomes\n ∂û/∂t̂ = Δû + f̂, where\n û(x̂, ŷ, 0) = φ̂ˢˢₙₘ(x̂, ŷ) and\n f̂(x̂, ŷ, t̂) = f̂₀ * exp(-(λ̂ₙₘ + Δλ̂) * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nOur solution then becomes\n û(x̂, ŷ, t̂) =\n (1 + f̂₀ / Δλ̂ * (1 - exp(-Δλ̂ * t̂))) * exp(-λ̂ₙₘ * t̂) * φ̂ˢˢₙₘ(x̂, ŷ).\nIn order to improve readability, we will drop the hats from all variable names.","category":"page"},{"location":"api/newtons_method/#Newton's-Method","page":"Newtons Method","title":"Newton's Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"NewtonsMethod","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newtons Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = Silent(),\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling solve_newton!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j may be changed from UpdateEvery(NewNewtonIteration) to some other UpdateSignalHandler that gets triggered less frequently, such as UpdateEvery(NewNewtonSolve). This can be used to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (possibly even a value from a previous solve_newton! of Newton's method). When Newton's method uses such an approximation, it is called the \"chord method\".\n\nIn addition, update_j can be set to an UpdateSignalHandler that gets triggered by signals that originate outside of Newton's method, such as UpdateEvery(NewTimeStep). It is possible to send any signal for updating j to Newton's method while it is not running by calling update!(::NewtonsMethod, cache, ::UpdateSignal, j!), where in this case j!(j) is a function that sets j in-place without any dependence on x (since x is not necessarily defined while Newton's method is not running, this version of j! does not take x as an argument). This can be used to make the approximation j(x[n]) ≈ j₀, where j₀ can have an arbitrary value.\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Newton-Krylov-Method","page":"Newtons Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n type = Val(Krylov.GmresSolver),\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = Silent(),\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling solve_krylov!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In solve_krylov!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...). The solver's type can be changed by specifying a different value for type, though this value has to be wrapped in a Val to avoid runtime compilation.\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newtons Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling get_rtol!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newtons Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newtons Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newtons Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling print_debug!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newtons Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newtons Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newtons Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling jvp!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newtons Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Convergence-Conditions","page":"Newtons Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling check_convergence!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newtons Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newtons Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newtons Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newtons Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#Update-Signals","page":"Newtons Method","title":"Update Signals","text":"","category":"section"},{"location":"api/newtons_method/","page":"Newtons Method","title":"Newtons Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateEveryDt\nUpdateSignal\nNewTimeStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nA boolean indicating if updates a value upon receiving an appropriate UpdateSignal. This is done by calling needs_update!(::UpdateSignalHandler, cache, ::UpdateSignal).\n\nThe cache can be obtained with allocate_cache(::UpdateSignalHandler, FT), where FT is the floating-point type of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal_type)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type update_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(n, update_signal_type, reset_signal_type = Nothing)\n\nAn UpdateSignalHandler that performs the update every n-th time it is needs_update! with an UpdateSignal of type update_signal_type. If reset_signal_type is specified, then the counter (which gets incremented from 0 to n and then gets reset to 0 when it is time to perform another update) is reset to 0 whenever the signal handler is needs_update! with an UpdateSignal of type reset_signal_type.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateEveryDt","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateEveryDt","text":"UpdateEveryDt(dt)\n\nAn UpdateSignalHandler that performs the update whenever it is needs_update! with an UpdateSignal of type NewTimeStep and the difference between the current time and the previous update time is no less than dt.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newtons Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewTimeStep","page":"Newtons Method","title":"ClimaTimeSteppers.NewTimeStep","text":"NewTimeStep(t)\n\nThe signal for a new time step at time t.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new needs_update! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"api/newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newtons Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"algorithm_formulations/lsrk/#Low-storage-Runge–Kutta-methods","page":"Old LSRK Formulations","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"or equivalently","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"algorithm_formulations/lsrk/","page":"Old LSRK Formulations","title":"Old LSRK Formulations","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,_,_) == A*u for someA(matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from SciMLBase.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"}]
+}
diff --git a/previews/PR203/siteinfo.js b/previews/PR203/siteinfo.js
new file mode 100644
index 000000000..a8d0a3ced
--- /dev/null
+++ b/previews/PR203/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR203";
diff --git a/previews/PR203/test_problems/diffusion_2d/index.html b/previews/PR203/test_problems/diffusion_2d/index.html
new file mode 100644
index 000000000..845836555
--- /dev/null
+++ b/previews/PR203/test_problems/diffusion_2d/index.html
@@ -0,0 +1,138 @@
+
+2D diffusion problem · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl on Thursday 19 November 2020. Using Julia version 1.5.3.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter , Christopher A Kennedy (1994), Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center , Hampton , VA, 1994.
+
This document was generated with Documenter.jl on Thursday 19 November 2020. Using Julia version 1.5.3.
diff --git a/previews/PR26/search_index.js b/previews/PR26/search_index.js
new file mode 100644
index 000000000..726ac5f7e
--- /dev/null
+++ b/previews/PR26/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel , O. Knoth , M. Arnold , R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J { \\ \" o } rg Wensch , Oswald Knoth , Alexander Galant (2009), Oswald Knoth , Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker , William C Skamarock (1998) and Louis J Wicker , William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = TimeMachine.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.initialize!","page":"Callbacks","title":"TimeMachine.Callbacks.initialize!","text":"TimeMachine.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.finalize!","page":"Callbacks","title":"TimeMachine.Callbacks.finalize!","text":"TimeMachine.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm; \n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#TimeMachine.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"TimeMachine.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"#TimeMachine.jl","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"","category":"section"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = TimeMachine","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#TimeMachine.LowStorageRungeKutta2N","page":"Algorithms","title":"TimeMachine.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK54CarpenterKennedy","page":"Algorithms","title":"TimeMachine.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter , Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"TimeMachine.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann , Richard Diehl , Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRKEulerMethod","page":"Algorithms","title":"TimeMachine.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#TimeMachine.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"TimeMachine.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Heuns","page":"Algorithms","title":"TimeMachine.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Ralstons","page":"Algorithms","title":"TimeMachine.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK33ShuOsher","page":"Algorithms","title":"TimeMachine.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu , Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK34SpiteriRuuth","page":"Algorithms","title":"TimeMachine.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri , Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#TimeMachine.AdditiveRungeKutta","page":"Algorithms","title":"TimeMachine.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK1ForwardBackwardEuler","page":"Algorithms","title":"TimeMachine.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher , Steven J. Ruuth , Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"TimeMachine.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher , Steven J. Ruuth , Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"TimeMachine.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy , Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy , Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#TimeMachine.Multirate","page":"Algorithms","title":"TimeMachine.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#TimeMachine.MultirateInfinitesimalStep","page":"Algorithms","title":"TimeMachine.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J { \\ \" o } rg Wensch , Oswald Knoth , Alexander Galant (2009) and Oswald Knoth , Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS2","page":"Algorithms","title":"TimeMachine.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS3C","page":"Algorithms","title":"TimeMachine.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS4","page":"Algorithms","title":"TimeMachine.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.MIS4a","page":"Algorithms","title":"TimeMachine.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.TVDMISA","page":"Algorithms","title":"TimeMachine.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.TVDMISB","page":"Algorithms","title":"TimeMachine.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth , Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#TimeMachine.WickerSkamarockRungeKutta","page":"Algorithms","title":"TimeMachine.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker , William C Skamarock (1998) and Louis J Wicker , William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.WSRK2","page":"Algorithms","title":"TimeMachine.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker , William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.WSRK3","page":"Algorithms","title":"TimeMachine.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker , William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR26/siteinfo.js b/previews/PR26/siteinfo.js
new file mode 100644
index 000000000..e420cf877
--- /dev/null
+++ b/previews/PR26/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR26";
diff --git a/previews/PR52/algorithms/index.html b/previews/PR52/algorithms/index.html
new file mode 100644
index 000000000..61497f805
--- /dev/null
+++ b/previews/PR52/algorithms/index.html
@@ -0,0 +1,2 @@
+
+Algorithms · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.23 on Friday 7 October 2022. Using Julia version 1.8.2.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
This document was generated with Documenter.jl version 0.27.23 on Friday 7 October 2022. Using Julia version 1.8.2.
diff --git a/previews/PR52/search_index.js b/previews/PR52/search_index.js
new file mode 100644
index 000000000..f296764eb
--- /dev/null
+++ b/previews/PR52/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm;\n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ARS","page":"Algorithms","title":"ARS","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARS111\nARS121\nARS343","category":"page"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR52/siteinfo.js b/previews/PR52/siteinfo.js
new file mode 100644
index 000000000..41ceb4a41
--- /dev/null
+++ b/previews/PR52/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR52";
diff --git a/previews/PR61/algorithms/index.html b/previews/PR61/algorithms/index.html
new file mode 100644
index 000000000..b54d2615c
--- /dev/null
+++ b/previews/PR61/algorithms/index.html
@@ -0,0 +1,2 @@
+
+Algorithms · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.18 on Saturday 24 September 2022. Using Julia version 1.7.3.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
This document was generated with Documenter.jl version 0.27.18 on Saturday 24 September 2022. Using Julia version 1.7.3.
diff --git a/previews/PR61/search_index.js b/previews/PR61/search_index.js
new file mode 100644
index 000000000..f296764eb
--- /dev/null
+++ b/previews/PR61/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm;\n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ARS","page":"Algorithms","title":"ARS","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARS111\nARS121\nARS343","category":"page"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR61/siteinfo.js b/previews/PR61/siteinfo.js
new file mode 100644
index 000000000..0a0b71c6c
--- /dev/null
+++ b/previews/PR61/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR61";
diff --git a/previews/PR8/algorithms/index.html b/previews/PR8/algorithms/index.html
new file mode 100644
index 000000000..6d9b4c64a
--- /dev/null
+++ b/previews/PR8/algorithms/index.html
@@ -0,0 +1,57 @@
+
+Algorithms · TimeMachine
The second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Heun's method.) Exact choice of coefficients from wikipedia page for Heun's method :)
References
@article{shu1988efficient,
+ title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},
+ author={Shu, Chi-Wang and Osher, Stanley},
+ journal={Journal of computational physics},
+ volume={77},
+ number={2},
+ pages={439--471},
+ year={1988},
+ publisher={Elsevier}
+}
+@article {Heun1900,
+ title = {Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabh"{a}ngigen Ver"{a}nderlichen}
+ author = {Heun, Karl},
+ journal = {Z. Math. Phys},
+ volume = {45},
+ pages = {23--38},
+ year = {1900}
+}
The second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Ralstons's method.) Exact choice of coefficients from wikipedia page for Heun's method :)
The third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Spiteri and Ruuth (1988)
References
@article{spiteri2002new,
+ title={A new class of optimal high-order strong-stability-preserving time discretization methods},
+ author={Spiteri, Raymond J and Ruuth, Steven J},
+ journal={SIAM Journal on Numerical Analysis},
+ volume={40},
+ number={2},
+ pages={469--491},
+ year={2002},
+ publisher={SIAM}
+}
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of Giraldo, Kelly and Constantinescu (2013).
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
References
Giraldo, F.X.; Kelly, J.F. and Constantinescu, E.M. (2013) "Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA)", SIAM Journal on Scientific Computing, 35(5): B1162–B1194 doi: 10.1137/120876034
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl on Thursday 23 July 2020. Using Julia version 1.4.2.
TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
This document was generated with Documenter.jl on Thursday 23 July 2020. Using Julia version 1.4.2.
diff --git a/previews/PR8/search_index.js b/previews/PR8/search_index.js
new file mode 100644
index 000000000..dcaa860bb
--- /dev/null
+++ b/previews/PR8/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"background/AdditiveRungeKutta/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/AdditiveRungeKutta/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/AdditiveRungeKutta/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/AdditiveRungeKutta/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/AdditiveRungeKutta/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"#TimeMachine.jl","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"","category":"section"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"TimeMachine.jl","title":"TimeMachine.jl","text":"TimeMachine.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#TimeMachine.LSRK54CarpenterKennedy","page":"Algorithms","title":"TimeMachine.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe fourth-order, 5-stage low storage Runge–Kutta scheme from Carpenter and Kennedy (1994). The coefficients are those from Solution 3 in the paper.\n\nReferences\n\nCarpenter, M.H.; Kennedy, C.A. (1994) \"Fourth-order 2N-storage Runge–Kutta schemes\", NASA Technical Memorandum 109112. http://hdl.handle.net/2060/19940028444\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"TimeMachine.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe fourth-order, 14-stage, low-storage, Runge–Kutta scheme of Niegemann, Diehl, and Busch (2012) with optimized stability region\n\nReferences\n\nNiegemann, J.; Diehl, R.; Busch, K. (2012) \"Efficient low-storage Runge–Kutta schemes with optimized stability regions\", Journal of Computational Physics 231(2): 364–372. doi: 10.1016/j.jcp.2011.09.003\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.LSRKEulerMethod","page":"Algorithms","title":"TimeMachine.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"SSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#TimeMachine.SSPRK22Heuns","page":"Algorithms","title":"TimeMachine.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Heun's method.) Exact choice of coefficients from wikipedia page for Heun's method :)\n\nReferences\n\n@article{shu1988efficient,\n title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},\n author={Shu, Chi-Wang and Osher, Stanley},\n journal={Journal of computational physics},\n volume={77},\n number={2},\n pages={439--471},\n year={1988},\n publisher={Elsevier}\n}\n@article {Heun1900,\n title = {Neue Methoden zur approximativen Integration der\n Differentialgleichungen einer unabh\"{a}ngigen Ver\"{a}nderlichen}\n author = {Heun, Karl},\n journal = {Z. Math. Phys},\n volume = {45},\n pages = {23--38},\n year = {1900}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK22Ralstons","page":"Algorithms","title":"TimeMachine.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988) (also known as Ralstons's method.) Exact choice of coefficients from wikipedia page for Heun's method :)\n\nReferences\n\n@article{shu1988efficient,\n title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},\n author={Shu, Chi-Wang and Osher, Stanley},\n journal={Journal of computational physics},\n volume={77},\n number={2},\n pages={439--471},\n year={1988},\n publisher={Elsevier}\n}\n@article{ralston1962runge,\n title={Runge-Kutta methods with minimum error bounds},\n author={Ralston, Anthony},\n journal={Mathematics of computation},\n volume={16},\n number={80},\n pages={431--437},\n year={1962},\n doi={10.1090/S0025-5718-1962-0150954-0}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK33ShuOsher","page":"Algorithms","title":"TimeMachine.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Shu and Osher (1988)\n\nReferences\n\n@article{shu1988efficient,\n title={Efficient implementation of essentially non-oscillatory shock-capturing schemes},\n author={Shu, Chi-Wang and Osher, Stanley},\n journal={Journal of computational physics},\n volume={77},\n number={2},\n pages={439--471},\n year={1988},\n publisher={Elsevier}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.SSPRK34SpiteriRuuth","page":"Algorithms","title":"TimeMachine.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Spiteri and Ruuth (1988)\n\nReferences\n\n@article{spiteri2002new,\n title={A new class of optimal high-order strong-stability-preserving time discretization methods},\n author={Spiteri, Raymond J and Ruuth, Steven J},\n journal={SIAM Journal on Numerical Analysis},\n volume={40},\n number={2},\n pages={469--491},\n year={2002},\n publisher={SIAM}\n}\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#TimeMachine.ARK1ForwardBackwardEuler","page":"Algorithms","title":"TimeMachine.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme, combining a forward Euler explicit step with a backward Euler implicit correction.\n\nReferences\n\nAscher, U.M.; Ruuth, S.J. and Spiteri, R.S. (1997) \"Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations\", Applied Numerical Mathematics, 25(2-3): 151–167. doi: 10.1016/S0168-9274(97)00056-1\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"TimeMachine.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme, combining the implicit and explicit midpoint methods.\n\nReferences\n\nAscher, U.M.; Ruuth, S.J. and Spiteri, R.S. (1997) \"Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations\", Applied Numerical Mathematics, 25(2-3): 151–167. doi: 10.1016/S0168-9274(97)00056-1\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"TimeMachine.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of Giraldo, Kelly and Constantinescu (2013).\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\nReferences\n\nGiraldo, F.X.; Kelly, J.F. and Constantinescu, E.M. (2013) \"Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA)\", SIAM Journal on Scientific Computing, 35(5): B1162–B1194 doi: 10.1137/120876034\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Kennedy and Carpenter (2019).\n\nReferences\n\nKennedy, C.A. and Carpenter, M.H. (2019) \"Higher-order additive Runge–Kutta schemes for ordinary differential equations\" Applied Numerical Mathematics. 136: 183–205. doi: 10.1016/j.apnum.2018.10.007\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#TimeMachine.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"TimeMachine.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Kennedy and Carpenter (2019).\n\nReferences\n\nKennedy, C.A. and Carpenter, M.H. (2019) \"Higher-order additive Runge–Kutta schemes for ordinary differential equations\" Applied Numerical Mathematics. 136: 183–205. doi: 10.1016/j.apnum.2018.10.007\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR8/siteinfo.js b/previews/PR8/siteinfo.js
new file mode 100644
index 000000000..f735e64ab
--- /dev/null
+++ b/previews/PR8/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR8";
diff --git a/previews/PR89/algorithms/index.html b/previews/PR89/algorithms/index.html
new file mode 100644
index 000000000..d64becaa3
--- /dev/null
+++ b/previews/PR89/algorithms/index.html
@@ -0,0 +1,2 @@
+
+Algorithms · ClimaTimeSteppers
Run the algorithm for the given arguments, using the cache to store intermediate values. Depending on the algorithm, the input arguments may also get modified.
A generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.
Generates an IMEXARKAlgorithm type from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.
The convergence orders of the provided methods are verified using test cases from ARKode. Plots of the solutions to these test cases, the errors of these solutions, and the convergence orders with respect to dt are shown below.
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.23 on Monday 5 December 2022. Using Julia version 1.8.3.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
Creates a DiffEqBase.DiscreteCallback that prints out a progress bar as the integrator runs.
Keywords
io::IO = stdout: output stream to which the progress bar is printed
min_update_time::Real = 0.5: minimum delay (in seconds) between prints
bar_title::String = "Progress: ": string that gets printed to the left of the progress bar
bar_length::Integer = 100: number of characters in the progress bar
show_tens_intervals::Bool = true: whether to add ticks above the progress bar that indicate the positions of 0%, 10%, 20%, ..., 100%; if this is false, only the ticks at 0% and 100% are shown
Creates a DiffEqBase.DiscreteCallback that prints out a progress bar as the integrator runs, along with an estimate of the time remaining until the integrator is finished, and also an optional user-specified message (e.g., diagnostic information about the integrator's state, or a Unicode plot).
This progress bar is designed to be overwritten on every update, so it should only be printed to a UNIX terminal (i.e., a terminal that supports clearing the previous line by printing the control sequence "\e[1A\r\e[0K").
The time remaining is estimated by computing an exponential moving average of the integrator's speed (seconds of real time that elapse per unit of integrator time) and multiplying this average speed by the remaining integrator time; the first integrator step is not included in the average so as to avoid biasing the estimate with compilation time.
Arguments
tType::Type = Float64: type of integrator.t
Keywords
io::IO = stdout: terminal output stream to which the progress bar is printed
min_update_time::Real = 0.5: minimum delay (in seconds) between prints
bar_title::String = "Progress: ": string that gets printed to the left of the progress bar
relative_bar_length::Real = 0.7: ratio between the number of characters in the progress bar and the width of the terminal (displaysize(io)[2])
eta_title::String = "Time Remaining: ": string that gets printed to the left of the time remaining
new_speed_weight::Real = 0.1: weight of the new speed in the formula for updating the exponential moving average — average := new_speed_weight * new_speed + (1 - new_speed_weight) * average
custom_message::Union{Nothing, Function} = nothing: an optional function of the form (integrator, terminal_width) -> String that generates a custom message whenever the progress bar is updated; the generated string can have multiple lines, and it is recommended to limit the length of each line to be no bigger than the terminal width in order to improve readability
clear_when_finished::Bool = true: whether to clear away the progress bar (and any other information that was printed) when the integrator is finished
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling run!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j can be changed from UpdateEvery(NewNewtonIteration()) to some other UpdateSignalHandler in order to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (this could even be a value from a previous run! of Newton's method). When Newton's method uses this approximation, it is called the "chord method".
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling run!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...) (note that type must be passed through in a Val struct), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In run!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...).
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling run!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling run!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling run!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling run!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
Updates a value upon receiving an appropriate UpdateSignal. This is done by calling run!(::UpdateSignalHandler, cache, ::UpdateSignal, f!, args...), where f! is function such that f!(args...) modifies the desired value in-place. The cache can be obtained with allocate_cache(::UpdateSignalHandler).
UpdateEveryN(update_signal, n, reset_n_signal = nothing)
An UpdateSignalHandler that executes the update every n-th time it is run! with update_signal. If reset_n_signal is specified, then the value of n is reset to 0 every time the signal handler is run! with reset_n_signal.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
This document was generated with Documenter.jl version 0.27.23 on Monday 5 December 2022. Using Julia version 1.8.3.
diff --git a/previews/PR89/search_index.js b/previews/PR89/search_index.js
new file mode 100644
index 000000000..f02fe4175
--- /dev/null
+++ b/previews/PR89/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"newtons_method/#Newton's-Method","page":"Newton's Method","title":"Newton's Method","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"NewtonsMethod","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newton's Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration()),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = false,\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling run!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j can be changed from UpdateEvery(NewNewtonIteration()) to some other UpdateSignalHandler in order to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (this could even be a value from a previous run! of Newton's method). When Newton's method uses this approximation, it is called the \"chord method\".\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Newton-Krylov-Method","page":"Newton's Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newton's Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n type = Val(Krylov.GmresSolver),\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = false,\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling run!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...) (note that type must be passed through in a Val struct), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In run!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...).\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newton's Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling run!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newton's Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newton's Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newton's Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling run!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newton's Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newton's Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newton's Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling run!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Convergence-Conditions","page":"Newton's Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newton's Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling run!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newton's Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newton's Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newton's Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newton's Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newton's Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newton's Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Update-Signals","page":"Newton's Method","title":"Update Signals","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateSignal\nNewStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nUpdates a value upon receiving an appropriate UpdateSignal. This is done by calling run!(::UpdateSignalHandler, cache, ::UpdateSignal, f!, args...), where f! is function such that f!(args...) modifies the desired value in-place. The cache can be obtained with allocate_cache(::UpdateSignalHandler).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal)\n\nAn UpdateSignalHandler that executes the update every time it is run! with update_signal.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(update_signal, n, reset_n_signal = nothing)\n\nAn UpdateSignalHandler that executes the update every n-th time it is run! with update_signal. If reset_n_signal is specified, then the value of n is reset to 0 every time the signal handler is run! with reset_n_signal.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.NewStep","page":"Newton's Method","title":"ClimaTimeSteppers.NewStep","text":"NewStep()\n\nThe signal for a new time step.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newton's Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new run! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newton's Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Progress-Callbacks","page":"Callbacks","title":"Progress Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"BasicProgressCallback\nTerminalProgressCallback","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.BasicProgressCallback","page":"Callbacks","title":"ClimaTimeSteppers.BasicProgressCallback","text":"BasicProgressCallback(; kwargs...)\n\nCreates a DiffEqBase.DiscreteCallback that prints out a progress bar as the integrator runs.\n\nKeywords\n\nio::IO = stdout: output stream to which the progress bar is printed\nmin_update_time::Real = 0.5: minimum delay (in seconds) between prints\nbar_title::String = \"Progress: \": string that gets printed to the left of the progress bar\nbar_length::Integer = 100: number of characters in the progress bar\nshow_tens_intervals::Bool = true: whether to add ticks above the progress bar that indicate the positions of 0%, 10%, 20%, ..., 100%; if this is false, only the ticks at 0% and 100% are shown\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.TerminalProgressCallback","page":"Callbacks","title":"ClimaTimeSteppers.TerminalProgressCallback","text":"TerminalProgressCallback([tType]; kwargs...)\n\nCreates a DiffEqBase.DiscreteCallback that prints out a progress bar as the integrator runs, along with an estimate of the time remaining until the integrator is finished, and also an optional user-specified message (e.g., diagnostic information about the integrator's state, or a Unicode plot).\n\nThis progress bar is designed to be overwritten on every update, so it should only be printed to a UNIX terminal (i.e., a terminal that supports clearing the previous line by printing the control sequence \"\\e[1A\\r\\e[0K\").\n\nThe time remaining is estimated by computing an exponential moving average of the integrator's speed (seconds of real time that elapse per unit of integrator time) and multiplying this average speed by the remaining integrator time; the first integrator step is not included in the average so as to avoid biasing the estimate with compilation time.\n\nArguments\n\ntType::Type = Float64: type of integrator.t\n\nKeywords\n\nio::IO = stdout: terminal output stream to which the progress bar is printed\nmin_update_time::Real = 0.5: minimum delay (in seconds) between prints\nbar_title::String = \"Progress: \": string that gets printed to the left of the progress bar\nrelative_bar_length::Real = 0.7: ratio between the number of characters in the progress bar and the width of the terminal (displaysize(io)[2])\neta_title::String = \"Time Remaining: \": string that gets printed to the left of the time remaining\nnew_speed_weight::Real = 0.1: weight of the new speed in the formula for updating the exponential moving average — average := new_speed_weight * new_speed + (1 - new_speed_weight) * average\ncustom_message::Union{Nothing, Function} = nothing: an optional function of the form (integrator, terminal_width) -> String that generates a custom message whenever the progress bar is updated; the generated string can have multiple lines, and it is recommended to limit the length of each line to be no bigger than the terminal width in order to improve readability\nclear_when_finished::Bool = true: whether to clear away the progress bar (and any other information that was printed) when the integrator is finished\n\n\n\n\n\n","category":"function"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,,) == A*u for some A (matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"algorithms/#Interface-and-OrdinaryDiffEq-compatibility","page":"Algorithms","title":"Interface and OrdinaryDiffEq compatibility","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"allocate_cache\nrun!\nForwardEulerODEFunction","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.allocate_cache","page":"Algorithms","title":"ClimaTimeSteppers.allocate_cache","text":"allocate_cache(alg, prototypes...)\n\nAllocate a cache that the algorithm will use during run!, given some values that are similar to values that need to be cached.\n\n\n\n\n\n","category":"function"},{"location":"algorithms/#ClimaTimeSteppers.run!","page":"Algorithms","title":"ClimaTimeSteppers.run!","text":"run!(alg, cache, args...)\n\nRun the algorithm for the given arguments, using the cache to store intermediate values. Depending on the algorithm, the input arguments may also get modified.\n\n\n\n\n\n","category":"function"},{"location":"algorithms/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"Algorithms","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#IMEX-ARK-methods","page":"Algorithms","title":"IMEX ARK methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"IMEXARKAlgorithm\nmake_IMEXARKAlgorithm","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.IMEXARKAlgorithm","page":"Algorithms","title":"ClimaTimeSteppers.IMEXARKAlgorithm","text":"IMEXARKAlgorithm <: DistributedODEAlgorithm\n\nA generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.make_IMEXARKAlgorithm","page":"Algorithms","title":"ClimaTimeSteppers.make_IMEXARKAlgorithm","text":"make_IMEXARKAlgorithm(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nGenerates an IMEXARKAlgorithm type from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.\n\n\n\n\n\n","category":"function"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"The convergence orders of the provided methods are verified using test cases from ARKode. Plots of the solutions to these test cases, the errors of these solutions, and the convergence orders with respect to dt are shown below.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"using Pkg\nPkg.activate(\"../../test\")\nPkg.instantiate()\ninclude(\"../../test/problems.jl\")\ninclude(\"../../test/utils.jl\")\ninclude(\"../../test/convergence.jl\")\nPkg.activate(\".\")","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Plots for ark_analytic: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Plots for ark_analytic_nonlin: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Plots for ark_analytic_sys: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ARS","page":"Algorithms","title":"ARS","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"TODO: ARS111, ARS121, and ARS343 should probably be types, and not constants, so that we can properly document them.","category":"page"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR89/siteinfo.js b/previews/PR89/siteinfo.js
new file mode 100644
index 000000000..6aa1b2ad7
--- /dev/null
+++ b/previews/PR89/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR89";
diff --git a/previews/PR91/algorithms/index.html b/previews/PR91/algorithms/index.html
new file mode 100644
index 000000000..72f910e24
--- /dev/null
+++ b/previews/PR91/algorithms/index.html
@@ -0,0 +1,2 @@
+
+Algorithms · ClimaTimeSteppers
Run the algorithm for the given arguments, using the cache to store intermediate values. Depending on the algorithm, the input arguments may also get modified.
A generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.
Generates an IMEXARKAlgorithm type from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.
The convergence orders of the provided methods are verified using test cases from ARKode. Plots of the solutions to these test cases, the errors of these solutions, and the convergence orders with respect to dt are shown below.
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.23 on Sunday 4 December 2022. Using Julia version 1.8.3.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Solves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling run!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.
Let x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].
If a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a "Newton-Krylov method"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a "Jacobian-free Newton-Krylov method".
If j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.
If j(x) changes sufficiently slowly, update_j can be changed from UpdateEvery(NewNewtonIteration()) to some other UpdateSignalHandler in order to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (this could even be a value from a previous run! of Newton's method). When Newton's method uses this approximation, it is called the "chord method".
If a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.
If verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.
Finds an approximation Δx[n] ≈ j(x[n]) \ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling run!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).
This is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In run!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...).
In the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).
If a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.
The keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).
All of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.
If verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.
Computes the value of rtol[n] for a Newton-Krylov method. This is done by calling run!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.
For a detailed discussion of forcing terms and their convergence guarantees, see "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).
A ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.
The ForcingTerm called "Choice 2" in the paper "Choosing the Forcing Terms in an Inexact Newton Method" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.
This forcing term was implemented instead of the one called "Choice 1" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas "Choice 1" also requires the norm of the final residual from the Krylov solver.
Prints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling run!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.
Prints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets "inverted" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.
Computes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling run!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).
Computes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.
A ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.
The first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.
From Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the "smoothness" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.
If only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.
Substituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.
Note that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.
A ForwardDiffStepSize that is described in the paper "Jacobian-free Newton–Krylov methods: a survey of approaches and applications" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.
Checks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling run!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.
A ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.
Instead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.
An abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.
Every subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).
Although cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.
Checks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).
Checks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.
Updates a value upon receiving an appropriate UpdateSignal. This is done by calling run!(::UpdateSignalHandler, cache, ::UpdateSignal, f!, args...), where f! is function such that f!(args...) modifies the desired value in-place. The cache can be obtained with allocate_cache(::UpdateSignalHandler).
UpdateEveryN(update_signal, n, reset_n_signal = nothing)
An UpdateSignalHandler that executes the update every n-th time it is run! with update_signal. If reset_n_signal is specified, then the value of n is reset to 0 every time the signal handler is run! with reset_n_signal.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
This document was generated with Documenter.jl version 0.27.23 on Sunday 4 December 2022. Using Julia version 1.8.3.
diff --git a/previews/PR91/search_index.js b/previews/PR91/search_index.js
new file mode 100644
index 000000000..5d7987f9a
--- /dev/null
+++ b/previews/PR91/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"newtons_method/#Newton's-Method","page":"Newton's Method","title":"Newton's Method","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"NewtonsMethod","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.NewtonsMethod","page":"Newton's Method","title":"ClimaTimeSteppers.NewtonsMethod","text":"NewtonsMethod(;\n max_iters = 1,\n update_j = UpdateEvery(NewNewtonIteration()),\n krylov_method = nothing,\n convergence_checker = nothing,\n verbose = false,\n)\n\nSolves the equation f(x) = 0, using the Jacobian (or an approximation of the Jacobian) j(x) = f'(x) if it is available. This is done by calling run!(::NewtonsMethod, cache, x, f!, j! = nothing), where f!(f, x) is a function that sets f(x) in-place and, if it is specified, j!(j, x) is a function that sets j(x) in-place. The x passed to Newton's method is modified in-place, and its initial value is used as a starting guess for the root. The cache can be obtained with allocate_cache(::NewtonsMethod, x_prototype, j_prototype = nothing), where x_prototype is similar to x and f(x), and, if it is specified, j_prototype is similar to j(x). In order for j(x) to be invertible, it must be a square matrix, which implies that x and f(x) must be similar to to each other.\n\nLet x[n] denote the value of x on the n-th Newton iteration (with x[0] denoting the initial value of x), and suppose that x[n] is sufficiently close to some root x̂ of f(x) to make the first-order approximation f(x̂) ≈ f(x[n]) + j(x[n]) * (x̂ - x[n]). Since f(x̂) = 0, the error on the n-th iteration is roughly x[n] - x̂ ≈ Δx[n], where Δx[n] = j(x[n]) \\ f(x[n]). Newton's method sets x[n + 1] to be the value of x̂ given by this approximation: x[n + 1] = x[n] - Δx[n].\n\nIf a Krylov method is specified, it gets used to compute the error Δx[n] = j(x[n]) \\ f(x[n]); otherwise, the error is directly computed by calling ldiv!(Δx, j, f). If the Krylov method uses a Jacobian-free JVP (Jacobian-vector product), j_prototype and j! do not need to be specified. When Newton's method uses a Krylov method, it is called a \"Newton-Krylov method\"; furthermore, when the Krylov method uses a Jacobian-free JVP, it is called a \"Jacobian-free Newton-Krylov method\".\n\nIf j_prototype is specified, it should not be an DenseMatrix. If it is, it has to be factorized with lu before ldiv! is called, which requires the allocation of additional memory. Instead, j_prototype should be an object that can directly be passed to ldiv!. For convenience, though, the use of an DenseMatrix is supported. However, Krylov.jl does not provide such support for its preconditioners, so, since the value computed with j! is used as a preconditioner in Krylov methods with a Jacobian-free JVP, using such a Krylov method requires specifying a j_prototype that can be passed to ldiv!.\n\nIf j(x) changes sufficiently slowly, update_j can be changed from UpdateEvery(NewNewtonIteration()) to some other UpdateSignalHandler in order to make the approximation j(x[n]) ≈ j(x₀), where x₀ is a previous value of x[n] (this could even be a value from a previous run! of Newton's method). When Newton's method uses this approximation, it is called the \"chord method\".\n\nIf a convergence checker is provided, it gets used to determine whether to stop iterating on iteration n based on the value x[n] and its error Δx[n]; otherwise, Newton's method iterates from n = 0 to n = max_iters. If the convergence checker determines that x[n] has not converged by the time n = max_iters, a warning gets printed.\n\nIf verbose is set to true, the norms of x[n] and Δx[n] get printed on every iteration. If there is no convergence checker, Δx[n] is not computed on the last iteration, so its final norm is not printed.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Newton-Krylov-Method","page":"Newton's Method","title":"Newton-Krylov Method","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"KrylovMethod\nForcingTerm\nConstantForcing\nEisenstatWalkerForcing\nKrylovMethodDebugger\nPrintConditionNumber","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.KrylovMethod","page":"Newton's Method","title":"ClimaTimeSteppers.KrylovMethod","text":"KrylovMethod(;\n jacobian_free_jvp = nothing,\n forcing_term = ConstantForcing(0),\n type = Krylov.GmresSolver,\n args = (20,),\n kwargs = (;),\n solve_kwargs = (;),\n disable_preconditioner = false,\n verbose = false,\n debugger = nothing,\n)\n\nFinds an approximation Δx[n] ≈ j(x[n]) \\ f(x[n]) for Newton's method such that ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖, where rtol[n] is the value of the forcing term on iteration n. This is done by calling run!(::KrylovMethod, cache, Δx, x, f!, f, n, j = nothing), where f is f(x[n]) and, if it is specified, j is either j(x[n]) or an approximation of j(x[n]). The Δx passed to a Krylov method is modified in-place. The cache can be obtained with allocate_cache(::KrylovMethod, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\nThis is primarily a wrapper for a Krylov.KrylovSolver from Krylov.jl. In allocate_cache, the solver is constructed with solver = type(l, l, args..., Krylov.ktypeof(x_prototype); kwargs...), where l = length(x_prototype) and Krylov.ktypeof(x_prototype) is a subtype of DenseVector that can be used to store x_prototype. By default, the solver is a Krylov.GmresSolver with a Krylov subspace size of 20 (the default Krylov subspace size for this solver in Krylov.jl). In run!, the solver is run with Krylov.solve!(solver, opj, f; M, ldiv, atol, rtol, verbose, solve_kwargs...).\n\nIn the call to Krylov.solve!, opj is a LinearOperator that represents j(x[n]), which the solver uses by evaluating mul!(jΔx, opj, Δx). If a Jacobian-free JVP (Jacobian-vector product) is specified, it gets used to construct opj and to evaluate the calls to mul!; otherwise, j itself gets used to construct opj, and the calls to mul! simplify to mul!(jΔx, j, Δx).\n\nIf a Jacobian-free JVP and j are both specified, and if disable_preconditioner is set to false, j is treated as an approximation of j(x[n]) and is used as the (left) preconditioner M in order to speed up the solver; otherwise, the preconditioner is simply set to the identity matrix I. The keyword argument ldiv is set to true so that the solver calls ldiv!(Δx′, M, f′) instead of mul!(Δx′, M, f′), where Δx′ and f′ denote internal variables of the solver that roughly correspond to Δx and f. In other words, setting ldiv to true makes the solver treat M as an approximation of j instead of as the inverse of an approximation of j.\n\nThe keyword argument atol is set to 0 because, if it is set to some other value, the inequality ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ changes to ‖f(x[n]) - j(x[n]) * Δx[n]‖ ≤ rtol[n] * ‖f(x[n])‖ + atol, which eliminates any convergence guarantees provided by the forcing term (in order for the Newton-Krylov method to converge, the right-hand side of this inequality must approach 0 as n increases, which cannot happen if atol is not 0).\n\nAll of the arguments and keyword arguments used to construct and run the solver can be modified using args, kwargs, and solve_kwargs. So, the default behavior of this wrapper can be easily overwritten, and any features of Krylov.jl that are not explicitly covered by this wrapper can still be used.\n\nIf verbose is true, the residual ‖f(x[n]) - j(x[n]) * Δx[n]‖ is printed on each iteration of the Krylov method. If a debugger is specified, it is run before the call to Kyrlov.solve!.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForcingTerm","page":"Newton's Method","title":"ClimaTimeSteppers.ForcingTerm","text":"ForcingTerm\n\nComputes the value of rtol[n] for a Newton-Krylov method. This is done by calling run!(::ForcingTerm, cache, f, n), which returns rtol[n]. The cache can be obtained with allocate_cache(::ForcingTerm, x_prototype), where x_prototype is similar to f.\n\nFor a detailed discussion of forcing terms and their convergence guarantees, see \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker (http://softlib.rice.edu/pub/CRPC-TRs/reports/CRPC-TR94463.pdf).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ConstantForcing","page":"Newton's Method","title":"ClimaTimeSteppers.ConstantForcing","text":"ConstantForcing(rtol)\n\nA ForcingTerm that always returns the value rtol, which must be in the interval [0, 1). If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge linearly with an asymptotic rate of at most rtol. If rtol is 0 (or eps(FT)), this forces the approximation of Δx[n] to be exact (or exact to within machine precision) and guarantees that the Newton-Krylov method will converge quadratically. Note that, although a smaller value of rtol guarantees faster asymptotic convergence, it also leads to a higher probability of oversolving.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.EisenstatWalkerForcing","page":"Newton's Method","title":"ClimaTimeSteppers.EisenstatWalkerForcing","text":"EisenstatWalkerForcing(;\n initial_rtol = 0.5,\n γ = 1,\n α = 2,\n min_rtol_threshold = 0.1,\n max_rtol = 0.9,\n)\n\nThe ForcingTerm called \"Choice 2\" in the paper \"Choosing the Forcing Terms in an Inexact Newton Method\" by S.C. Eisenstat and H.F. Walker. The values of initial_rtol, min_rtol_threshold, and max_rtol must be in the interval [0, 1), the value of γ must be in the interval [0, 1], and the value of α must be in the interval (1, 2]. These values can all be tuned to prevent the Newton-Krylov method from oversolving. If x and f! satisfy certain assumptions, this forcing term guarantees that the Newton-Krylov method will converge with order α. Note that, although a larger value of α guarantees a higher convergence order, it also leads to a higher probability of oversolving.\n\nThis forcing term was implemented instead of the one called \"Choice 1\" because it has a significantly simpler implementation–-it only requires the value of ‖f(x[n])‖ to compute rtol[n], whereas \"Choice 1\" also requires the norm of the final residual from the Krylov solver.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.KrylovMethodDebugger","page":"Newton's Method","title":"ClimaTimeSteppers.KrylovMethodDebugger","text":"KrylovMethodDebugger\n\nPrints information about the Jacobian matrix j and the preconditioner M (if it is available) that are passed to a Krylov method. This is done by calling run!(::KrylovMethodDebugger, cache, j, M). The cache can be obtained with allocate_cache(::KrylovMethodDebugger, x_prototype), where x_prototype is similar to x.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.PrintConditionNumber","page":"Newton's Method","title":"ClimaTimeSteppers.PrintConditionNumber","text":"PrintConditionNumber()\n\nPrints the condition number of the Jacobian matrix j, and, if a preconditioner M is available, also prints the condition number of inv(M) * j (i.e., the matrix that actually gets \"inverted\" by the Krylov method). This requires computing dense representations of j and inv(M) * j, which is likely to be significantly slower than the Krylov method itself.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Jacobian-free-Newton-Krylov-Method","page":"Newton's Method","title":"Jacobian-free Newton-Krylov Method","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"JacobianFreeJVP\nForwardDiffJVP\nForwardDiffStepSize\nForwardDiffStepSize1\nForwardDiffStepSize2\nForwardDiffStepSize3","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.JacobianFreeJVP","page":"Newton's Method","title":"ClimaTimeSteppers.JacobianFreeJVP","text":"JacobianFreeJVP\n\nComputes the Jacobian-vector product j(x[n]) * Δx[n] for a Newton-Krylov method without directly using the Jacobian j(x[n]), and instead only using x[n], f(x[n]), and other function evaluations f(x′). This is done by calling run!(::JacobianFreeJVP, cache, jΔx, Δx, x, f!, f). The jΔx passed to a Jacobian-free JVP is modified in-place. The cache can be obtained with allocate_cache(::JacobianFreeJVP, x_prototype), where x_prototype is similar to x (and also to Δx and f).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffJVP","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffJVP","text":"ForwardDiffJVP(; default_step = ForwardDiffStepSize3(), step_adjustment = 1)\n\nComputes the Jacobian-vector product using the forward difference approximation j(x) * Δx = (f(x + ε * Δx) - f(x)) / ε, where ε = step_adjustment * default_step(Δx, x).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize","text":"ForwardDiffStepSize\n\nComputes a default step size for the forward difference approximation of the Jacobian-vector product. This is done by calling default_step(Δx, x), where default_step is a ForwardDiffStepSize.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize1","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize1","text":"ForwardDiffStepSize1()\n\nA ForwardDiffStepSize that is derived based on the notes here: https://web.engr.oregonstate.edu/~webbky/MAE40205020files/Section%204%20Roundoff%20and%20Truncation%20Error.pdf. Although it is not often used with Newton-Krylov methods in practice, it can provide some intuition for for how to set the value of step_adjustment in a ForwardDiffJVP.\n\nThe first-order Taylor series expansion of f(x + ε * Δx) around x is f(x + ε * Δx) = f(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx), where j(x) = f'(x) and e_trunc is the expansion's truncation error. Due to roundoff error, we are unable to directly compute the value of f(x); instead, we can only determine f̂(x), where f(x) = f̂(x) + e_round(x). Substituting this into the expansion tells us that f̂(x + ε * Δx) + e_round(x + ε * Δx) = f̂(x) + e_round(x) + j(x) * (ε * Δx) + e_trunc(x, ε * Δx). Rearranging this gives us the Jacobian-vector product j(x) * Δx = (f̂(x + ε * Δx) - f̂(x)) / ε - e_trunc(x, ε * Δx) / ε + (e_round(x + ε * Δx) - e_round(x)) / ε. So, the normed error of the forward difference approximation of this product is ‖error‖ = ‖(f̂(x + ε * Δx) - f̂(x)) / ε - j(x) * Δx‖ = = ‖e_trunc(x, ε * Δx) - e_round(x + ε * Δx) + e_round(x)‖ / ε. We can use the triangle inequality to get the upper bound ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + ‖e_round(x + ε * Δx)‖ + ‖e_round(x)‖) / ε. If ε is sufficiently small, we can approximate ‖e_round(x + ε * Δx)‖ ≈ ‖e_round(x)‖. This simplifies the upper bound to ‖error‖ ≤ (‖e_trunc(x, ε * Δx)‖ + 2 * ‖e_round(x)‖) / ε.\n\nFrom Taylor's theorem (for multivariate vector-valued functions), the truncation error of the first-order expansion is bounded by ‖e_trunc(x, ε * Δx)‖ ≤ (sup_{x̂ ∈ X} ‖f''(x̂)‖) / 2 * ‖ε * Δx‖^2, where X is a closed ball around x that contains x + ε * Δx (see https://math.stackexchange.com/questions/3478229 for a proof of this). Let us define the value S = ‖f(x)‖ / sup_{x̂ ∈ X} ‖f''(x̂)‖. By default, we will assume that S ≈ 1, but we will let users pass other values to indicate the \"smoothness\" of f(x) (a large value of S should indicate that the Hessian tensor of f(x) has a small norm compared to f(x) itself). We then have that ‖e_trunc(x, ε * Δx)‖| ≤ ε^2 / (2 * S) * ‖Δx‖^2 * ‖f(x)‖.\n\nIf only the last bit in each component of f(x) can be altered by roundoff error, then the i-th component of e_round(x) is bounded by |e_round(x)[i]| ≤ eps(f(x)[i]). More generally, we can assume that there is some constant R (by default, we will assume that R ≈ 1) such that |e_round(x)[i]| ≤ R * eps(f(x)[i]). We can also make the approximation (which is accurate to within eps(FT)) eps(f(x)[i]) ≈ eps(FT) * |f(x)[i]|. This implies that |e_round(x)[i]| ≤ R * eps(FT) * |f(x)[i]|. Since this is true for every component of e_round(x) and f(x), we find that ‖e_round(x)‖ ≤ R * eps(FT) * ‖f(x)‖.\n\nSubstituting the bounds on the truncation and roundoff errors into the bound on the overall error gives us ‖error‖ ≤ ε / (2 * S) * ‖Δx‖^2 * ‖f(x)‖ + 2 / ε * R * eps(FT) * ‖f(x)‖. Differentiating the right-hand side with respect to ε and setting the result equal to 0 (and noting that the second derivative is always positive) tells us that this upper bound is minimized when ε = step_adjustment * sqrt(eps(FT)) / ‖Δx‖, where step_adjustment = 2 * sqrt(S * R). By default, we will assume that step_adjustment = 1, but it should be made larger when f is very smooth or has a large roundoff error.\n\nNote that, if we were to replace the forward difference approximation in the derivation above with a central difference approximation, the square root would end up being replaced with a cube root (or, more generally, with an n-th root for a finite difference approximation of order n - 1).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize2","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize2","text":"ForwardDiffStepSize2()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the step size used by the Fortran package NITSOL.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ForwardDiffStepSize3","page":"Newton's Method","title":"ClimaTimeSteppers.ForwardDiffStepSize3","text":"ForwardDiffStepSize3()\n\nA ForwardDiffStepSize that is described in the paper \"Jacobian-free Newton–Krylov methods: a survey of approaches and applications\" by D.A. Knoll and D.E. Keyes. According to the paper, this is the average step size one gets when using a certain forward difference approximation for each Jacobian element.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Convergence-Conditions","page":"Newton's Method","title":"Convergence Conditions","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"ConvergenceChecker\nConvergenceCondition\nMaximumError\nMaximumRelativeError\nMaximumErrorReduction\nMinimumRateOfConvergence\nMultipleConditions","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.ConvergenceChecker","page":"Newton's Method","title":"ClimaTimeSteppers.ConvergenceChecker","text":"ConvergenceChecker(;\n norm_condition,\n component_condition,\n condition_combiner,\n norm = LinearAlgebra.norm,\n)\n\nChecks whether a sequence val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = val[iter] .- L. This is done by calling run!(::ConvergenceChecker, cache, val, err, iter), where val = val[iter] and err = err[iter]. If the value of L is not known, err can be an approximation of err[iter]. The cache for a ConvergenceChecker can be obtained with allocate_cache(::ConvergenceChecker, val_prototype), where val_prototype is similar to val and err.\n\nA ConvergenceChecker can perform two types of checks–-it can check whether norm(val) and norm(err) satisfy some ConvergenceCondition, and it can check whether all the components of abs.(val) and abs.(err) individually satisfy some ConvergenceCondition. These two checks can be combined with either & or |. If one of the checks is not needed, the corresponding ConvergenceCondition can be set to nothing.\n\nInstead of LinearAlgebra.norm, norm can be set to anything that will convert val and err to non-negative scalar values.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.ConvergenceCondition","page":"Newton's Method","title":"ClimaTimeSteppers.ConvergenceCondition","text":"ConvergenceCondition\n\nAn abstract type for objects that can check whether a sequence of non-negative scalar values val[0], val[1], val[2], ... has converged to some limit L, given the errors err[iter] = |val[iter] - L|.\n\nEvery subtype of ConvergenceCondition must define has_converged(::ConvergenceCondition, cache, val, err, iter). The cache, which is set to nothing by default, may be used to store information from previous iterations that is useful for determining convergence. In order to have access to a cache of some particular type, a subtype of ConvergenceCondition should define cache_type(::ConvergenceCondition, ::Type{FT}). To specify on which iterations this cache should be updated, it should define needs_cache_update(::ConvergenceCondition, iter). To specify how the cache should be update on those iterations, it should define updated_cache(::ConvergenceCondition, cache, val, err, iter).\n\nAlthough cache_type can call promote_type to prevent potential type instability errors, this should be avoided in order to ensure that users write type-stable code.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MaximumError","page":"Newton's Method","title":"ClimaTimeSteppers.MaximumError","text":"MaximumError(max_err)\n\nChecks whether err[iter] ≤ max_err. Since err[iter] ≥ 0, this can only be true if max_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MaximumRelativeError","page":"Newton's Method","title":"ClimaTimeSteppers.MaximumRelativeError","text":"MaximumRelativeError(max_rel_err)\n\nChecks whether err[iter] ≤ max_rel_err * val[iter]. Since err[iter] ≥ 0 and val[iter] ≥ 0, this can only be true if max_rel_err ≥ 0.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MaximumErrorReduction","page":"Newton's Method","title":"ClimaTimeSteppers.MaximumErrorReduction","text":"MaximumErrorReduction(max_reduction)\n\nChecks whether err[iter] ≤ max_reduction * err[0] for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if max_reduction ≥ 0. Also, it must be the case that max_reduction ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[0]).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MinimumRateOfConvergence","page":"Newton's Method","title":"ClimaTimeSteppers.MinimumRateOfConvergence","text":"MinimumRateOfConvergence(rate, order = 1)\n\nChecks whether err[iter] ≥ rate * err[iter - 1]^order for all iter ≥ 1. Since err[iter] ≥ 0, this can only be true if rate ≥ 0. Also, if order == 1, it must be the case that rate ≤ 1 in order for the sequence to not diverge (i.e., to avoid err[iter] > err[iter - 1]). In addition, if err[iter] < 1 for all sufficiently large values of iter, it must be the case that order ≥ 1 for the sequence to not diverge.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.MultipleConditions","page":"Newton's Method","title":"ClimaTimeSteppers.MultipleConditions","text":"MultipleConditions(condition_combiner = all, conditions...)\n\nChecks multiple ConvergenceConditions, combining their results with either all or any.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#Update-Signals","page":"Newton's Method","title":"Update Signals","text":"","category":"section"},{"location":"newtons_method/","page":"Newton's Method","title":"Newton's Method","text":"UpdateSignalHandler\nUpdateEvery\nUpdateEveryN\nUpdateSignal\nNewStep\nNewNewtonSolve\nNewNewtonIteration","category":"page"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateSignalHandler","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateSignalHandler","text":"UpdateSignalHandler\n\nUpdates a value upon receiving an appropriate UpdateSignal. This is done by calling run!(::UpdateSignalHandler, cache, ::UpdateSignal, f!, args...), where f! is function such that f!(args...) modifies the desired value in-place. The cache can be obtained with allocate_cache(::UpdateSignalHandler).\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateEvery","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateEvery","text":"UpdateEvery(update_signal)\n\nAn UpdateSignalHandler that executes the update every time it is run! with update_signal.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateEveryN","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateEveryN","text":"UpdateEveryN(update_signal, n, reset_n_signal = nothing)\n\nAn UpdateSignalHandler that executes the update every n-th time it is run! with update_signal. If reset_n_signal is specified, then the value of n is reset to 0 every time the signal handler is run! with reset_n_signal.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.UpdateSignal","page":"Newton's Method","title":"ClimaTimeSteppers.UpdateSignal","text":"UpdateSignal\n\nA signal that gets passed to an UpdateSignalHandler whenever a certain operation is performed.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.NewStep","page":"Newton's Method","title":"ClimaTimeSteppers.NewStep","text":"NewStep()\n\nThe signal for a new time step.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.NewNewtonSolve","page":"Newton's Method","title":"ClimaTimeSteppers.NewNewtonSolve","text":"NewNewtonSolve()\n\nThe signal for a new run! of Newton's method, which occurs on every implicit Runge-Kutta stage of the integrator.\n\n\n\n\n\n","category":"type"},{"location":"newtons_method/#ClimaTimeSteppers.NewNewtonIteration","page":"Newton's Method","title":"ClimaTimeSteppers.NewNewtonIteration","text":"NewNewtonIteration()\n\nThe signal for a new iteration of Newton's method.\n\n\n\n\n\n","category":"type"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"Callbacks","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks","text":"ClimaTimeSteppers.Callbacks\n\nA suite of callback functions to be used with the ClimaTimeSteppers.jl ODE solvers.\n\n\n\n\n\n","category":"module"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm_ctx::ClimaComms.AbstractCommsContext;\n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn ClimaComms context must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers","category":"page"},{"location":"#ClimaTimeSteppers","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers","text":"ClimaTimeSteppers\n\nOrdinary differential equation solvers\n\nJuliaDiffEq terminology:\n\nFunction: the right-hand side function df/dt.\nby default, a function gets wrapped in an ODEFunction\ndefine new IncrementingODEFunction to support incrementing function calls.\nProblem: Function, initial u, time span, parameters and options\ndu/dt = f(u,p,t) = fL(u,p,t) + fR(u,p,t)\nfR(u,p,t) == f(u.p,t) - fL(u,p,t) fL(u,,) == A*u for some A (matrix free)\nSplitODEProlem(fL, fR)\n\nODEProblem from OrdinaryDiffEq.jl\nuse jac option to ODEFunction for linear + full IMEX (https://docs.sciml.ai/latest/features/performanceoverloads/#odeexplicit_jac-1)\nSplitODEProblem for linear + remainder IMEX\nMultirateODEProblem for true multirate\nAlgorithm: small objects (often singleton) which indicate what algorithm + options (e.g. linear solver type)\ndefine new abstract DistributedODEAlgorithm, algorithms in this pacakge will be subtypes of this\ndefine new Multirate for multirate solvers\nIntegrator: contains everything necessary to solve. Used as:\ndefine new DistributedODEIntegrator for solvers in this package\ninit(prob, alg, options...) => integrator step!(int) => runs single step solve!(int) => runs it to end solve(prob, alg, options...) => init + solve!\nSolution (not implemented): contains the \"solution\" to the ODE.\n\n\n\n\n\n","category":"module"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"algorithms/#Interface-and-OrdinaryDiffEq-compatibility","page":"Algorithms","title":"Interface and OrdinaryDiffEq compatibility","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"allocate_cache\nrun!\nForwardEulerODEFunction","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.allocate_cache","page":"Algorithms","title":"ClimaTimeSteppers.allocate_cache","text":"allocate_cache(alg, prototypes...)\n\nAllocate a cache that the algorithm will use during run!, given some values that are similar to values that need to be cached.\n\n\n\n\n\n","category":"function"},{"location":"algorithms/#ClimaTimeSteppers.run!","page":"Algorithms","title":"ClimaTimeSteppers.run!","text":"run!(alg, cache, args...)\n\nRun the algorithm for the given arguments, using the cache to store intermediate values. Depending on the algorithm, the input arguments may also get modified.\n\n\n\n\n\n","category":"function"},{"location":"algorithms/#ClimaTimeSteppers.ForwardEulerODEFunction","page":"Algorithms","title":"ClimaTimeSteppers.ForwardEulerODEFunction","text":"ForwardEulerODEFunction(f; jac_prototype, Wfact, tgrad)\n\nAn ODE function wrapper where f(un, u, p, t, dt) provides a forward Euler update\n\nun .= u .+ dt * f(u, p, t)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#IMEX-ARK-methods","page":"Algorithms","title":"IMEX ARK methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"IMEXARKAlgorithm\nmake_IMEXARKAlgorithm","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.IMEXARKAlgorithm","page":"Algorithms","title":"ClimaTimeSteppers.IMEXARKAlgorithm","text":"IMEXARKAlgorithm <: DistributedODEAlgorithm\n\nA generic implementation of an IMEX ARK algorithm that can handle arbitrary Butcher tableaus and problems specified using either ForwardEulerODEFunctions or regular ODEFunctions.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.make_IMEXARKAlgorithm","page":"Algorithms","title":"ClimaTimeSteppers.make_IMEXARKAlgorithm","text":"make_IMEXARKAlgorithm(; a_exp, b_exp, c_exp, a_imp, b_imp, c_imp)\n\nGenerates an IMEXARKAlgorithm type from an IMEX ARK Butcher tableau. Only a_exp and a_imp are required arguments; the default values for b_exp and b_imp assume that the algorithm is FSAL (first same as last), and the default values for c_exp and c_imp assume that the algorithm is internally consistent.\n\n\n\n\n\n","category":"function"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"The convergence orders of the provided methods are verified using test cases from ARKode. Plots of the solutions to these test cases, the errors of these solutions, and the convergence orders with respect to dt are shown below.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"using Pkg\nPkg.activate(\"../../test\")\nPkg.instantiate()\ninclude(\"../../test/problems.jl\")\ninclude(\"../../test/utils.jl\")\ninclude(\"../../test/convergence.jl\")\nPkg.activate(\".\")","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Plots for ark_analytic: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Plots for ark_analytic_nonlin: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Plots for ark_analytic_sys: (Image: ) (Image: ) (Image: )","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ARS","page":"Algorithms","title":"ARS","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"TODO: ARS111, ARS121, and ARS343 should probably be types, and not constants, so that we can properly document them.","category":"page"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/previews/PR91/siteinfo.js b/previews/PR91/siteinfo.js
new file mode 100644
index 000000000..899a4614b
--- /dev/null
+++ b/previews/PR91/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "previews/PR91";
diff --git a/stable b/stable
new file mode 120000
index 000000000..951ae7cbd
--- /dev/null
+++ b/stable
@@ -0,0 +1 @@
+v0.7.7
\ No newline at end of file
diff --git a/v0.1 b/v0.1
new file mode 120000
index 000000000..a1c2c6a9f
--- /dev/null
+++ b/v0.1
@@ -0,0 +1 @@
+v0.1.1
\ No newline at end of file
diff --git a/v0.1.0/algorithms/index.html b/v0.1.0/algorithms/index.html
new file mode 100644
index 000000000..9cd4f9083
--- /dev/null
+++ b/v0.1.0/algorithms/index.html
@@ -0,0 +1,2 @@
+
+Algorithms · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.15 on Thursday 31 March 2022. Using Julia version 1.7.2.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
This document was generated with Documenter.jl version 0.27.15 on Thursday 31 March 2022. Using Julia version 1.7.2.
diff --git a/v0.1.0/search_index.js b/v0.1.0/search_index.js
new file mode 100644
index 000000000..d39a4387b
--- /dev/null
+++ b/v0.1.0/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm; \n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/v0.1.0/siteinfo.js b/v0.1.0/siteinfo.js
new file mode 100644
index 000000000..a7a85ce61
--- /dev/null
+++ b/v0.1.0/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "v0.1.0";
diff --git a/v0.1.1/algorithms/index.html b/v0.1.1/algorithms/index.html
new file mode 100644
index 000000000..b94653ce5
--- /dev/null
+++ b/v0.1.1/algorithms/index.html
@@ -0,0 +1,2 @@
+
+Algorithms · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.15 on Wednesday 6 April 2022. Using Julia version 1.7.2.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
This document was generated with Documenter.jl version 0.27.15 on Wednesday 6 April 2022. Using Julia version 1.7.2.
diff --git a/v0.1.1/search_index.js b/v0.1.1/search_index.js
new file mode 100644
index 000000000..d39a4387b
--- /dev/null
+++ b/v0.1.1/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm; \n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/v0.1.1/siteinfo.js b/v0.1.1/siteinfo.js
new file mode 100644
index 000000000..20089fd73
--- /dev/null
+++ b/v0.1.1/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "v0.1.1";
diff --git a/v0.2 b/v0.2
new file mode 120000
index 000000000..3788c7726
--- /dev/null
+++ b/v0.2
@@ -0,0 +1 @@
+v0.2.6
\ No newline at end of file
diff --git a/v0.2.0/algorithms/index.html b/v0.2.0/algorithms/index.html
new file mode 100644
index 000000000..898157ffc
--- /dev/null
+++ b/v0.2.0/algorithms/index.html
@@ -0,0 +1,2 @@
+
+Algorithms · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function $f(u) = f_L(u) + f_R(t)$ where $f_L(u) = L u$ is a linear operator which is treated implicitly, and $f_R(u)$ is the remainder to be treated explicitly. Typically we will be given either the pair $(f_R, f_L)$, which we will term the remainder form, or $(f, f_L)$ which we will term the full form.
The value on the $i$th stage $U^{(i)}$ is
\[U^{(i)} = u^n + \Delta t \sum_{j=1}^i \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
which can be written as the solution to the linear problem:
\[W U^{(i)} = \hat U^{(i)}\]
where
\[\hat U^{(i)} = u^n + \Delta t \sum_{j=1}^{i-1} \tilde a_{ij} f_L(U^{(j)})
+ + \Delta t \sum_{j=1}^{i-1} a_{ij} f_R(U^{(j)})\]
F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034
Settings
This document was generated with Documenter.jl version 0.27.15 on Monday 11 April 2022. Using Julia version 1.7.2.
The method is defined in terms of the lower-triangular matrices $\alpha$, $\beta$ and $\gamma$, with $d_i = \sum_j \beta_{ij}$, $c_i = (I - \alpha - \gamma)^{-1} d$ and $\tilde c = \alpha c$.
ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.
Mark H Carpenter, Christopher A Kennedy, Fourth-order $2N$-storage Runge–Kutta schemes, Technical Report NASA TM-109112, National Aeronautics and Space Administration, Langley Research Center, Hampton, VA, 1994.
Karl Heun, Neue Methoden zur approximativen Integration der
+ Differentialgleichungen einer unabhängigen Veränderlichen, Z. Math. Phys, 45, 23–38, 1900.
This document was generated with Documenter.jl version 0.27.15 on Monday 11 April 2022. Using Julia version 1.7.2.
diff --git a/v0.2.0/search_index.js b/v0.2.0/search_index.js
new file mode 100644
index 000000000..9c7ddccdf
--- /dev/null
+++ b/v0.2.0/search_index.js
@@ -0,0 +1,3 @@
+var documenterSearchIndex = {"docs":
+[{"location":"references/#References","page":"References","title":"References","text":"","category":"section"},{"location":"references/","page":"References","title":"References","text":"","category":"page"},{"location":"background/lsrk/#Low-storage-Runge–Kutta-methods","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"","category":"section"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"LSRK methods are self-starting, with U^(1) = u^n, and then using stage updates of the form","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\ndU^(i) = f(U^(i) t + c_i Delta t) + A_i dU^(i-1)\nU^(i+1) = U^(i) + Delta t B_i dU^(i)\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"where A_1 = c_1 = 0 (implying dU^(1) = f(u^n t)), with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"This allows the updates to be performed with only two copies of the state vector (so long as f can be evaluated in incrementing form).","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"It can be written as an RK scheme with Butcher tableau coefficients defined by the recurrences","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_ii = 0 \na_ij = B_j + A_j+1 a_ij+1\nb_N = B_N \nb_i = B_i + A_i+1 b_i+1\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"or equivalently","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"beginaligned\na_jj = 0 \na_ij = a_i-1j + B_i-1 prod_k=j+1^i-1 A_k\nendaligned","category":"page"},{"location":"background/lsrk/","page":"Low-storage Runge–Kutta methods","title":"Low-storage Runge–Kutta methods","text":"with b_j treated analogously as a_N+1j.","category":"page"},{"location":"background/mrrk/#Multirate-Runge-Kutta","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given a problem with two components that operate at two rates:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdudt = f_F(ut) + f_S(ut)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where f_F is the fast component, and f_S is the slow component.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"M. Schlegel, O. Knoth, M. Arnold, R. Wolke (2012) defines the following method.","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Given an outer explicit Runge–Kutta scheme with tableau (abc)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"We can define the stage values U^(i) = v_i(tau_i) as the solution to the inner ODE problem","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = sum_j=1^i fraca_ij - a_i-1jc_i - c_i-1 f_S (U^(j) tau_j)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where tau_i = t + Delta t c_i, with initial condition v_i(tau_i-1) = U^(i-1). If c_i == c_i-1, we can treat it as a correction step:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"U^(i) = U^(i-1) + Delta t fracsum_j=1^i (a_ij - a_i-1j)c_i - c_i-1 f_S (U^(j) tau_i)","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The final summation stage treating analogously to i=N+1, with a_N+1j = b_j and c_N+1 = 1.","category":"page"},{"location":"background/mrrk/#Low-storage","page":"Multirate Runge Kutta","title":"Low-storage","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"If using a low-storage Runge–Kutta method is used as an outer solver, then this reduces to","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"fracdv_idtau\n = fracB_i-1c_i - c_i-1 dU_S^(i-1)\n + f_F(v_i tau)\nquad tau in tau_i-1 tau","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"where","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"dU_S^(i) = f_S(U^(i) tau_i) + A_i dU_S^(i-1)","category":"page"},{"location":"background/mrrk/#Multirate-Infinitesimal-Step-(MIS)","page":"Multirate Runge Kutta","title":"Multirate Infinitesimal Step (MIS)","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Multirate Infinitesimal Step (MIS) methods (J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009), Oswald Knoth, Joerg Wensch (2014))","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (0)\n = u^n + sum_j=1^i-1 alpha_ij (U^(j) - u^n)\n\nfracdv_idtau\n = sum_j=1^i-1 fracgamma_ijd_i Delta t (U^(j) - u^n)\n + sum_j=1^i fracbeta_ijd_i f_S (U^(j) t + Delta t c_i)\n + f_F(v_i t^n + Delta t tilde c_i + fracc_i - tilde c_id_i tau)\nquad tau in 0 Delta t d_i\n\nU^(i) = v_i(Delta t d_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"The method is defined in terms of the lower-triangular matrices alpha, beta and gamma, with d_i = sum_j beta_ij, c_i = (I - alpha - gamma)^-1 d and tilde c = alpha c.","category":"page"},{"location":"background/mrrk/#Wicker-Skamarock","page":"Multirate Runge Kutta","title":"Wicker Skamarock","text":"","category":"section"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002) define RK2 and RK3 multirate schemes:","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"beginaligned\nv_i (t) = u^n\n\nfracdv_idtau\n = f_S (U^(i-1) t + Delta t c_i-1)\n + f_F(v_i tau)\nquad tau in t t+ Delta t c_i \n\nU^(i) = v_i(t + Delta t c_i)\nendaligned","category":"page"},{"location":"background/mrrk/","page":"Multirate Runge Kutta","title":"Multirate Runge Kutta","text":"which corresponds to an MIS method with alpha = gamma = 0 and beta = operatornamediag(c).","category":"page"},{"location":"background/ark/#Additive-Runge–Kutta","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function f(u) = f_L(u) + f_R(t) where f_L(u) = L u is a linear operator which is treated implicitly, and f_R(u) is the remainder to be treated explicitly. Typically we will be given either the pair (f_R f_L), which we will term the remainder form, or (f f_L) which we will term the full form. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The value on the ith stage U^(i) is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"U^(i) = u^n + Delta t sum_j=1^i tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"which can be written as the solution to the linear problem:","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W U^(i) = hat U^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t sum_j=1^i-1 tilde a_ij f_L(U^(j)) \n + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W = (I - Delta t tilde a_ii L)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"The next step is then defined as","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"u^n+1 = u^n + Delta t sum_i=1^N b_i f_L(U^(i)) + f_R(U^(i)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"When an iterative solver is used, an initial value bar U^(i) can be chosen by an explicit approximation","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t sum_j=1^i-1 (a_ij - tilde a_ij) f_L(U^(j)) ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"By convention, tilde a_11 = 0, so that U^(1) = u^n, and for all other stages the implicit coefficients tilde a_ii are the same. ","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is time-invariant and Delta t is constantm, then if using a direct solver, W only needs to be factorized once.","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Alternatively if an iterative solver is used used, we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar U^(i) = u^n + Delta t sum_j=1^i-1 a_ij f_L(U^(j)) + f_R(U^(j)) \n = hat U^(i) + Delta t L sum_j=1^i-1 (a_ij - tilde a_ij) U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"at the cost of one evaluation of f_L.","category":"page"},{"location":"background/ark/#Reducing-evaluations-and-storage","page":"Additive Runge–Kutta","title":"Reducing evaluations and storage","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If the linear operator L is constant, then we are able to avoid evaluating the f_L explicitly.","category":"page"},{"location":"background/ark/#Remainder-form","page":"Additive Runge–Kutta","title":"Remainder form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If we are given f_L and f_R, we can avoid storing f_L(U^(j)) by further defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and writing","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L( Omega^(i) ) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"This can be rewritten into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i)\n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_R(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f_R(U^(j)) + Omega^(i) + Delta t sum_j=1^i-1 a_ij f_L(U^(j))\n = hat V^(i) + Delta t L sum_j=1^i-1 a_ij U^(j)","category":"page"},{"location":"background/ark/#Full-form","page":"Additive Runge–Kutta","title":"Full form","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Similary, if we are given f and f_L, we can avoid storing f_L(U^(j)) by defining","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"Omega^(i) = sum_j=1^i-1 fractilde a_ij - a_ijtilde a_ii U^(j)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"so that we can write","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat U^(i) = u^n + Delta t tilde a_ii f_L(Omega^(i)) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"As above, we can rewrite into an offset linear problem","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"W V^(i) = hat V^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"where","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"V^(i) = U^(i) + Omega^(i)","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"and","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"hat V^(i) \n = hat U_(i) + (I - Delta t tilde a_ii L) Omega^(i) \n = u^n + Omega^(i) + Delta t sum_j=1^i-1 a_ij f(U^(j))","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"If using an iterative method, an initial guess is","category":"page"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"bar V^(i) = bar U^(i) + Omega^(i)\n = u^n + Delta t sum_j=1^i-1 a_ij f(U^(j)) \n = hat V^(i) - Omega^(i)","category":"page"},{"location":"background/ark/#References","page":"Additive Runge–Kutta","title":"References","text":"","category":"section"},{"location":"background/ark/","page":"Additive Runge–Kutta","title":"Additive Runge–Kutta","text":"F. X. Giraldo, J. F. Kelly, and E. M. Constantinescu (2013). Implicit-Explicit Formulations of a Three-Dimensional Nonhydrostatic Unified Model of the Atmosphere (NUMA) SIAM Journal on Scientific Computing 35(5), B1162-B1194, doi:10.1137/120876034","category":"page"},{"location":"callbacks/#Callbacks","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"CurrentModule = ClimaTimeSteppers.Callbacks","category":"page"},{"location":"callbacks/#Interfaces","page":"Callbacks","title":"Interfaces","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"initialize!\nfinalize!","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.initialize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.initialize!","text":"ClimaTimeSteppers.Callbacks.initialize!(f!::F, integrator)\n\nInitialize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.finalize!","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.finalize!","text":"ClimaTimeSteppers.Callbacks.finalize!(f!::F, integrator)\n\nFinalize a callback event for callbacks of type F. By default this does nothing, but can be extended for new callback events.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#Callbacks-2","page":"Callbacks","title":"Callbacks","text":"","category":"section"},{"location":"callbacks/","page":"Callbacks","title":"Callbacks","text":"EveryXWallTimeSeconds\nEveryXSimulationTime\nEveryXSimulationSteps","category":"page"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXWallTimeSeconds","text":"EveryXWallTimeSeconds(f!, Δwt, comm::MPI.Comm;\n atinit=false)\n\nTrigger f!(integrator) every Δwt wallclock seconds.\n\nAn MPI communicator comm must be provided to synchronize timing across all ranks.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f!(integrator) will additionally be triggered at initialization, otherwise the first trigger will be after Δwt seconds.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationTime","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationTime","text":"EveryXSimulationTime(f!, Δt;\n atinit=false)\n\nTrigger f!(integrator) every Δt simulation time.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit=true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δt simulation time.\n\n\n\n\n\n","category":"function"},{"location":"callbacks/#ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","page":"Callbacks","title":"ClimaTimeSteppers.Callbacks.EveryXSimulationSteps","text":"EveryXSimulationSteps(f!, Δsteps;\n atinit=false)\n\nTrigger f!(integrator) every Δsteps simulation steps.\n\nCallbacks.initialize! and Callbacks.finalize! can be defined for f!.\n\nIf atinit==true, then f! will additionally be triggered at initialization. Otherwise the first trigger will be after Δsteps.\n\n\n\n\n\n","category":"function"},{"location":"#ClimaTimeSteppers.jl","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"","category":"section"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is a suite of ordinary differential equation (ODE) solvers for use as time-stepping methods in a partial differential equation (PDE) solver, such as ClimateMachine.jl. They are specifically written to support distributed and GPU computation, while minimising the memory footprint.","category":"page"},{"location":"","page":"ClimaTimeSteppers.jl","title":"ClimaTimeSteppers.jl","text":"ClimaTimeSteppers.jl is built on top of DiffEqBase.jl, and aims to be compatible with the DifferentialEquations.jl ecosystem.","category":"page"},{"location":"background/ssprk/#Strong-Stability-Preserving-Runge–Kutta-methods","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"","category":"section"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"SSPRK methods are self-starting, with U^(1) = u^n, and subsequent stage updates of the form","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"beginaligned\nU^(i+1) = A_i1 u^n + A_i2 U^(i) + Delta t B_i f(U^(i) t + c_i Delta t)\nendaligned","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"with the value at the next step being the N+1th stage value u^n+1 = U^(N+1)).","category":"page"},{"location":"background/ssprk/","page":"Strong Stability Preserving Runge–Kutta methods","title":"Strong Stability Preserving Runge–Kutta methods","text":"This allows the updates to be performed with only three copies of the state vector (storing u^n, U^(i) and f(U^(i)t)).","category":"page"},{"location":"algorithms/#Algorithms","page":"Algorithms","title":"Algorithms","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"CurrentModule = ClimaTimeSteppers","category":"page"},{"location":"algorithms/#Low-Storage-Runge–Kutta-(LSRK)-methods","page":"Algorithms","title":"Low-Storage Runge–Kutta (LSRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Low-storage Runger–Kutta methods reduce the number stages that need to be stored. The methods below require only one additional storage vector.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"An IncrementingODEProblem must be used.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"LowStorageRungeKutta2N\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\nLSRKEulerMethod","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.LowStorageRungeKutta2N","page":"Algorithms","title":"ClimaTimeSteppers.LowStorageRungeKutta2N","text":"LowStorageRungeKutta2N <: DistributedODEAlgorithm\n\nA class of low-storage Runge-Kutta algorithms, which use only one additional copy of the state vector u (often referred to as 2N schemes).\n\nThe available implementations are:\n\nLSRKEulerMethod\nLSRK54CarpenterKennedy\nLSRK144NiegemannDiehlBusch\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK54CarpenterKennedy","page":"Algorithms","title":"ClimaTimeSteppers.LSRK54CarpenterKennedy","text":"LSRK54CarpenterKennedy()\n\nThe 4th-order, 5-stage [LowStorageRungeKutta2N])(ref) scheme from Solution 3 of Mark H Carpenter, Christopher A Kennedy (1994).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","page":"Algorithms","title":"ClimaTimeSteppers.LSRK144NiegemannDiehlBusch","text":"LSRK144NiegemannDiehlBusch()\n\nThe 4th-order, 14-stage, [LowStorageRungeKutta2N])(ref) scheme of Jens Niegemann, Richard Diehl, Kurt Busch (2012) with optimized stability region\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.LSRKEulerMethod","page":"Algorithms","title":"ClimaTimeSteppers.LSRKEulerMethod","text":"LSRKEulerMethod()\n\nAn implementation of explicit Euler method using LowStorageRungeKutta2N infrastructure. This is mainly for debugging.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Strong-Stability-Preserving-Runge–Kutta-(SSPRK)-methods","page":"Algorithms","title":"Strong Stability-Preserving Runge–Kutta (SSPRK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"StrongStabilityPreservingRungeKutta\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.StrongStabilityPreservingRungeKutta","text":"StrongStabilityPreservingRungeKutta <: DistributedODEAlgorithm\n\nA class of Strong Stability Preserving Runge–Kutta methods. These require two additional copies of the state vector.\n\nThe available implementations are:\n\nSSPRK22Heuns\nSSPRK22Ralstons\nSSPRK33ShuOsher\nSSPRK34SpiteriRuuth\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Heuns","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Heuns","text":"SSPRK22Heuns()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Heun's method (Heun1900.\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK22Ralstons","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK22Ralstons","text":"SSPRK22Ralstons()\n\nThe second-order, 2-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988), also known as Ralstons's method (Anthony Ralston (1962).\n\nExact choice of coefficients from wikipedia page for Heun's method :)\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK33ShuOsher","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK33ShuOsher","text":"SSPRK33ShuOsher()\n\nThe third-order, 3-stage, strong-stability-preserving, Runge–Kutta scheme of Chi-Wang Shu, Stanley Osher (1988).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.SSPRK34SpiteriRuuth","page":"Algorithms","title":"ClimaTimeSteppers.SSPRK34SpiteriRuuth","text":"SSPRK34SpiteriRuuth()\n\nThe third-order, 4-stage, strong-stability-preserving, Runge–Kutta scheme of Raymond J Spiteri, Steven J Ruuth (2002).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Additive-Runge–Kutta-(ARK)-methods","page":"Algorithms","title":"Additive Runge–Kutta (ARK) methods","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"fracdudt = Lu + f_R(ut)","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Currently ARK methods require a SplitODEProblem.","category":"page"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"AdditiveRungeKutta\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.AdditiveRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.AdditiveRungeKutta","text":"AdditiveRungeKutta\n\nIMEX (IMplicit-EXplicit) algorithms using ARK (Additively-partitioned Runge-Kutta) methods.\n\nThe available implementations are:\n\nARK1ForwardBackwardEuler\nARK2ImplicitExplicitMidpoint\nARK2GiraldoKellyConstantinescu\nARK437L2SA1KennedyCarpenter\nARK548L2SA2KennedyCarpenter\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK1ForwardBackwardEuler","page":"Algorithms","title":"ClimaTimeSteppers.ARK1ForwardBackwardEuler","text":"ARK1ForwardBackwardEuler(linsolve)\n\nA first-order-accurate two-stage additive Runge–Kutta scheme of Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining a forward Euler explicit step with a backward Euler implicit correction.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","page":"Algorithms","title":"ClimaTimeSteppers.ARK2ImplicitExplicitMidpoint","text":"ARK2ImplicitExplicitMidpoint(linsolve)\n\nA second-order, two-stage additive Runge–Kutta scheme Uri M. Ascher, Steven J. Ruuth, Raymond J. Spiteri (1997), combining the implicit and explicit midpoint methods.\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","page":"Algorithms","title":"ClimaTimeSteppers.ARK2GiraldoKellyConstantinescu","text":"ARK2GiraldoKellyConstantinescu(linsolve; paperversion=false)\n\nThe second-order, 3-stage additive Runge–Kutta scheme of GKC2013.\n\nIf the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK437L2SA1KennedyCarpenter","text":"ARK437L2SA1KennedyCarpenter(linsolve)\n\nThe fourth-order, 7-stage additive Runge–Kutta scheme ARK4(3)7L[2]SA₁ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","page":"Algorithms","title":"ClimaTimeSteppers.ARK548L2SA2KennedyCarpenter","text":"ARK548L2SA2KennedyCarpenter(linsolve)\n\nThe fifth-order, 8-stage additive Runge–Kutta scheme ARK5(4)8L[2]SA₂ of Christopher A Kennedy, Mark H Carpenter (2019).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate","page":"Algorithms","title":"Multirate","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"Multirate","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.Multirate","page":"Algorithms","title":"ClimaTimeSteppers.Multirate","text":"Multirate(fast, slow)\n\nA multirate Runge–Kutta scheme, combining fast and slow algorithms\n\nslow can be any algorithm providing methods for the following functions\n\ninit_inner(prob, outercache, dt)\nupdate_inner!(innerinteg, outercache, f_slow, u, p, t, dt, stage)\n\nAlgorithms which currently support this are:\n\nLowStorageRungeKutta2N\nMultirateInfinitesimalStep\nWickerSkamarockRungeKutta\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Multirate-Infinitesimal-Step","page":"Algorithms","title":"Multirate Infinitesimal Step","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"MultirateInfinitesimalStep\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.MultirateInfinitesimalStep","page":"Algorithms","title":"ClimaTimeSteppers.MultirateInfinitesimalStep","text":"MultirateInfinitesimalStep\n\nMultirate Infinitesimal Step (MIS) methods of J{\\\"o}rg Wensch, Oswald Knoth, Alexander Galant (2009) and Oswald Knoth, Joerg Wensch (2014).\n\nThe available implementations are:\n\nMIS2\nMIS3C\nMIS4\nMIS4a\nTVDMISA\nTVDMISB\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS2","page":"Algorithms","title":"ClimaTimeSteppers.MIS2","text":"MIS2()\n\nThe MIS2 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS3C","page":"Algorithms","title":"ClimaTimeSteppers.MIS3C","text":"MIS3C()\n\nThe MIS3C Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4","page":"Algorithms","title":"ClimaTimeSteppers.MIS4","text":"MIS4()\n\nThe MIS4 Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.MIS4a","page":"Algorithms","title":"ClimaTimeSteppers.MIS4a","text":"MIS4a()\n\nThe MIS4a Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISA","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISA","text":"TVDMISA()\n\nThe TVDMISA Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.TVDMISB","page":"Algorithms","title":"ClimaTimeSteppers.TVDMISB","text":"TVDMISB()\n\nThe TVDMISB Total Variation Diminishing (TVD) Multirate Infinitesimal Step (MIS) method of Oswald Knoth, Joerg Wensch (2014).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#Wicker–Skamarock","page":"Algorithms","title":"Wicker–Skamarock","text":"","category":"section"},{"location":"algorithms/","page":"Algorithms","title":"Algorithms","text":"WickerSkamarockRungeKutta\nWSRK2\nWSRK3","category":"page"},{"location":"algorithms/#ClimaTimeSteppers.WickerSkamarockRungeKutta","page":"Algorithms","title":"ClimaTimeSteppers.WickerSkamarockRungeKutta","text":"WickerSkamarockRungeKutta <: DistributedODEAlgorithm\n\nClass of multirate algorithms developed in Louis J Wicker, William C Skamarock (1998) and Louis J Wicker, William C Skamarock (2002), which can be used as slow methods in Multirate.\n\nThese require two additional copies of the state vector u.\n\nAvailable implementations are:\n\nWSRK2\nWSRK3\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK2","page":"Algorithms","title":"ClimaTimeSteppers.WSRK2","text":"WSRK2()\n\nThe 2 stage, 2nd order RK2 scheme of Louis J Wicker, William C Skamarock (1998).\n\n\n\n\n\n","category":"type"},{"location":"algorithms/#ClimaTimeSteppers.WSRK3","page":"Algorithms","title":"ClimaTimeSteppers.WSRK3","text":"WSRK3()\n\nThe 3 stage, 2nd order (3rd order for linear problems) RK3 scheme of Louis J Wicker, William C Skamarock (2002).\n\n\n\n\n\n","category":"type"}]
+}
diff --git a/v0.2.0/siteinfo.js b/v0.2.0/siteinfo.js
new file mode 100644
index 000000000..057c824fd
--- /dev/null
+++ b/v0.2.0/siteinfo.js
@@ -0,0 +1 @@
+var DOCUMENTER_CURRENT_VERSION = "v0.2.0";
diff --git a/v0.2.1/algorithms/index.html b/v0.2.1/algorithms/index.html
new file mode 100644
index 000000000..99a006012
--- /dev/null
+++ b/v0.2.1/algorithms/index.html
@@ -0,0 +1,2 @@
+
+Algorithms · ClimaTimeSteppers
ARK methods are IMEX (Implicit-Explicit) methods based on splitting the ODE function into a linear and remainder components:
\[\frac{du}{dt} = Lu + f_R(u,t)\]
where the linear part is solved implicitly. All the algorithms below take a linsolve argument to specify the linear solver to be used. See the linsolve specification of DifferentialEquations.jl.
The second-order, 3-stage additive Runge–Kutta scheme of GKC2013.
If the keyword paperversion=true is used, the coefficients from the paper are used. Otherwise it uses coefficients that make the scheme (much) more stable but less accurate
