delta_max and fix cabs2

docs/nstrophy_doc.tex

@@ -103,6 +103,88 @@ We truncate the Fourier modes and assume that $\hat u_k=0$ if $|k_1|>K_1$ or $|k
 \end{equation}
 \bigskip
 
+\point{\bf Runge-Kutta methods}.
+To solve the equation numerically, we will use Runge-Kutta methods, which compute an approximate value $\hat u_k^{(n)}$ for $\hat u_k(t_n)$.
+{\tt nstrophy} supports the 4th order Runge-Kutta ({\tt RK4}) and 2nd order Runge-Kutta ({\tt RK2}) algorithms.
+In addition, several variable step methods are implemented:
+\begin{itemize}
+  \item the Runge-Kutta-Dormand-Prince method ({\tt RKDP54}), which is of 5th order, and adjusts the step by comparing to a 4th order method;
+  \item the Runge-Kutta-Fehlberg method ({\tt RKF45}), which is of 4th order, and adjusts the step by comparing to a 5th order method;
+  \item the Runge-Kutta-Bogacki-Shampine method ({\tt RKBS32}), which is of 3d order, and adjusts the step by comparing to a 2nd order method.
+\end{itemize}
+In these adaptive step methods, two steps are computed at different orders: $\hat u_k^{(n)}$ and $\hat U_k^{(n)}$, the step size is adjusted at every step in such a way that the error is small enough:
+\begin{equation}
+  \|\hat u^{(n)}-\hat U^{(n)}\|
+  <\epsilon_{\mathrm{target}}
+\end{equation}
+for some given $\epsilon_{\mathrm{target}}$, set using the {\tt adaptive\_tolerance} parameter.
+The choice of the norm matters, and will be discussed below.
+If the error is larger than the target, then the step size is decreased.
+How this is done depends on the order of algorithm.
+If the order is $q$ (here we mean the smaller of the two orders, so 4 for {\tt RKDP54} and {\tt RKF45} and 2 for {\tt RKBS32}), then we expect
+\begin{equation}
+  \|\hat u^{(n)}-\hat U^{(n)}\|=\delta_n^qC_n
+  .
+\end{equation}
+We wish to set $\delta_{n+1}$ so that
+\begin{equation}
+  \delta_{n+1}^qC_n=\epsilon_{\mathrm{target}}
+\end{equation}
+so
+\begin{equation}
+  \delta_{n+1}
+  =\left(\frac{\epsilon_{\mathrm{target}}}{C_n}\right)^{\frac1q}
+  =\delta_n\left(\frac{\epsilon_{\mathrm{target}}}{\|\hat u^{(n)}-\hat U^{(n)}\|}\right)^{\frac1q}
+  .
+  \label{adaptive_delta}
+\end{equation}
+(Actually, to be safe and ensure that $\delta$ decreases sufficiently, we multiply this by a safety factor that can be set using the {\tt adaptive\_factor} parameter.)
+If the error is smaller than the target, we increase $\delta$ using\-~(\ref{adaptive_delta}) (without the safety factor).
+To be safe, we also set a maximal value for $\delta$ via the {\tt max\_delta} parameter.
+\bigskip
+
+\indent
+The choice of the norm $\|\cdot\|$ matters.
+\begin{itemize}
+  \item A naive choice is to take $\|\cdot\|$ to be the normalized $L_1$ norm:
+  \begin{equation}
+    \|f\|:=
+    \frac1{\mathcal N}\sum_k|f_k|
+    ,\quad
+    \mathcal N:=\sum_k|\hat u_k^{(n)}-\hat u_k^{(n-1)}|
+    .
+  \end{equation}
+
+  \item Empirically, we have found that $|\hat u-\hat U|$ behaves like $k^{-3}$ for {\tt RKDP54} and {\tt RKF45}, and like $k^{-\frac32}$ for {\tt RKBS32}, so a norm of the form
+  \begin{equation}
+    \|f\|:=\frac1{\mathcal N}\sum_k|f_k|k^{-3}
+    ,\quad
+    \mathcal N:=\sum_k|\hat u_k^{(n)}-\hat u_k^{(n-1)}|k^{-3}
+  \end{equation}
+  or
+  \begin{equation}
+    \|f\|:=\frac1{\mathcal N}\sum_k|f_k|k^{-\frac32}
+    ,\quad
+    \mathcal N:=\sum_k|\hat u_k^{(n)}-\hat u_k^{(n-1)}|k^{-\frac32}
+  \end{equation}
+  are sensible choices.
+
+  \item
+  Another option is to define a norm based on the expression of the enstrophy\-~(\ref{enstrophy}):
+  \begin{equation}
+    \|f\|:=\frac1{\mathcal N}\sqrt{\sum_k k^2|f_k|^2}
+    \quad
+    \mathcal N:=\sqrt{\sum_k k^2|\hat u_k^{(n)}|^2}
+    .
+  \end{equation}
+  Doing so controls the error of the enstrophy through
+  \begin{equation}
+    \mathcal N^2|\mathcal En(\hat u)-\mathcal En(\hat U)|\equiv|\|\hat u\|^2-\|\hat U\|^2|\leqslant \|\hat u-\hat U\|(\|\hat u\|+\|\hat U\|)
+    .
+  \end{equation}
+\end{itemize}
+\bigskip
+
 \point{\bf Reality}.
 Since $U$ is real, $\hat U_{-k}=\hat U_k^*$, and so
 \begin{equation}
@@ -271,6 +353,7 @@ and
     +e^{-\frac{4\pi^2}{L^2}\nu t}\sqrt{E(0)}
   \right)^2
   .
+  \label{enstrophy}
 \end{equation}
 \bigskip