Add background info for ODE solvers

[dennisYatunin]

Purpose

This PR adds a new page to the docs, background/ode_solvers.md.

Content

The new documentation is a detailed LaTeX writeup of how our IMEX ARK and IMEX SSPRK methods are formulated and why they are formulated that way. It also provides a brief description of standard IMEX ARK methods, assuming minimal background knowledge from users.

Aside from the writeup, this PR also removes stage_callback! from the ClimaODEFunction. This function was originally introduced to allow filtering, but filtering of the explicit tendencies can already be achieved through dss!, and filtering of the implicit tendencies is a bad idea (see current EDMF filtering revamp). Without stage_callback!, the current implementation of IMEX ARK and IMEX SSPRK methods exactly matches what is in the writeup.

---

• I have read and checked the items on the review checklist.

[tapios]

This looks fine (however, I did not check every detail).

Please add the relevant references for the methods, especially the SSP IMEX. And mention that the SSP property relies on being able to write the method as a sequence of Euler steps.

For next time, though, please keep the documentation succinct (no need to introduce textbook concepts about timesteppers), and please focus implementation and documentation on what we directly need, i.e., SSPRK(3,3) for SSP IMEX. As it is, this is overly general, making it harder to understand the simple case we need and use.

[tapios]

Suggested change

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

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

[tapios]

Suggested change

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 discontinuous Galerkin 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 discontinuous state 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:

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:

[dennisYatunin]

I've addressed all of Tapio's comments. I'll go ahead and r+ this.

[dennisYatunin]

bors r+

[bors]

Build succeeded:

• buildkite/climatimesteppers-ci
• docbuild
• format
• test-os (1.8, macos-latest)
• test-os (1.8, ubuntu-latest)
• test-os (1.8, windows-latest)