%%%%%%%%%%%%%%%%%%%%%definitions%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\input{../../doc/related_pages/header.tex}
\input{../../doc/related_pages/newcommands.tex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%DOCUMENT%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}

\title{
The full-F electromagnetic model in toroidal geometry \textsc{Feltor}}
\author{ M.~Wiesenberger and M.~Held}
\maketitle

\begin{abstract}
The purpose of this document is to describe the programs
\texttt{feltor\_hpc.cu, feltor.cu, feltor\_diag.cu} and to an extend
\texttt{geometry\_diag.cu}. The goal is to provide
information such that a user can avoid to look
into the actual codes on the one side and connect
the presented formulas to relevant journal publications on the other.

The program \texttt{feltor/inc/geometries/geometry\_diag.cu}
analyses the magnetic field geometry.
\texttt{feltor\_hpc.cu} and \texttt{feltor.cu} are programs for global 3d isothermal electromagnetic full-F gyro-fluid simulations.
\texttt{feltor/diag/feltor\_diag.cu} is a program to analyse the output
file(s) of \texttt{feltor\_hpc.cu}.

\end{abstract}
\tableofcontents

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The magnetic field}\label{sec:magnetic}
We assume a three-dimensional flat space with arbitrary coordinate
system $\vec x :=\{x_0, x_1, x_2\}$, metric
tensor $g_{ij}$ and volume element $\sqrt{g} := \sqrt{\det g}$.
Given a vector field $\vec B(\vec x)$ with unit vector $\bhat(\vec x) := (\vec B/B)({\vec x})$
we can define various differential operations.
\begin{table*}[htbp]
\caption{Definitions of geometric operators with $b^i$ the contra-variant components of $\bhat$ and $g^{ij}$ the contra-variant elements of the metric tensor. We assume $(\vn\times\bhat)_\parallel = 0$. Note that $\vec K = \vec K_\kappa + \vec{ K_{\vn B}}$.
% Explicit expressions of these quantities
% depend on the choice of the magnetic field and the underlying coordinate system.
}\label{tab:operators}
\centering
\rowcolors{2}{gray!25}{white}
\begin{longtable}{lll>{\RaggedRight}p{7cm}}
%\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Symbol} & \textbf{Definition} \\
\midrule
    Perpendicular Poisson bracket&
    $\left[.,.\right]_\perp$ &
    $\left[f,g\right]_\perp := \bhat \cdot \left(\vec{\vn} f \times\vn g\right) =
    b_i \varepsilon^{ijk}\partial_j f\partial_k g/\sqrt{g}$  \\
    Projection Tensor&
    $h $ & $h^{ij} := g^{ij} - b^ib^j $   \quad \text{ Note }$ h^2=h$\\
    %Alignment Tensor&
    %$t $ & $ t^{ij} := b^ib^j$\\
    Perpendicular Gradient&
    $\np $&
    $ \np f := \bhat\times(\vn f\times \bhat ) \equiv
    h \cdot \vn f$ \\
    Perpendicular Divergence&
    $\np^\dagger $&
    $ \np^\dagger \cdot \vec v := -\nc( h \cdot \vec v) = -\nc\vec v_\perp$ \\
    Perpendicular Laplacian &
    $\Delta_\perp $ &
    $ \Delta_\perp f:= \nc (\np f)
    = \nc( h\cdot\vn f) \equiv -\np^\dagger\cdot\np$  \\
    Curl-b Curvature Operator&
    $\mathcal K_{\vn\times\bhat}$ &
    $\mathcal K_{\vn\times\bhat}(f) := \vec{ K_{\vn\times\bhat} }\cn f = \frac{1}{B}(\vn \times \bhat)\cn f$ \\[4pt]
    Grad-B Curvature Operator &
    $\mathcal K_{\vn B} $ &
    $\mathcal K_{\vn B}(f) := \vec{ K_{\vn B}} \cn f = \frac{1}{B}(\bhat \times\vn \ln B)\cn f$ \\[4pt]
    Curvature Operator&
    $\mathcal K$ &
    $\mathcal{K}(f):=\vec{ K} \cn f =
     \vec{\vn}\cdot\left(\frac{\bhat\times\vec{\vn} f}{B}\right) =\vn \times \frac{\bhat}{B} \cn f$,\\[4pt]
    Parallel derivative&
    $\npar $&
    $ \npar f := \bhat\cdot\vn f$ \quad  Notice $\nc\bhat = -\npar\ln B$ \\
     Parallel Laplacian&
     $\Delta_\parallel $&
     $\Delta_\parallel f:= \vec{\vn} \cdot ( \bhat\bhat\cdot\vec{\vn} f )$\\
\bottomrule
\end{longtable}
\end{table*}
with $b^i$ the contra- and $b_i$ the co-variant components of $\bhat$, and
$\eps^{ijk}$ the Levi-Civita symbols.
Explicit expressions for the above expressions
depend on the choice of the magnetic field and the underlying coordinate system.
Note that we have
\begin{align}
    \nc \vec{ K_{\vn\times\bhat}}
&= -\nc \vec{ K_{\vn B}} = -\vec{K_{\vn\times\bhat}}\cn\ln B, \\
    \vec\nc\vec{ K} &= 0, \\
    \mathcal K(f) &=
     \vn\times\frac{\bhat}{B}\cn f
    = \mathcal K_{\vn\times\bhat}(f) + \mathcal K_{\vn B}(f),\\
    \vec{ K_{\vn\times\bhat}} - \vec{ K_{\vn B}} &= \frac{1}{B^2} (\vn \times \vec B), \\
    \npar \ln B &= -\vec\nc\bhat.
    \label{eq:curl_curvature}
\end{align}
The last equality holds if $\vec\nc \vec B = 0$.
Note that in any arbitrary coordinate system we have
\begin{align}
(\vn f)^i = g^{ij}\partial_j f ~, \quad
\nc \vec v = \frac{1}{\sqrt{g}}\partial_i \left(\sqrt{g} v^i\right) ~, \quad
(\vec v \times \vec w)^i = \frac{1}{\sqrt{g}}\varepsilon^{ijk} v_jw_k ~.
%\label{}
\end{align}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Coordinate system}\label{sec:cylmetric}
We employ cylindrical coordinates \( (R,Z,\varphi) \), with \(\varphi\) anti directed to the geometric toroidal angle ({\bf clockwise} if viewed from above) to
obtain a right handed system. The parametric representation in Cartesian \((x,y,z)\) coordinates is therefore simply:
\begin{align}
 x &= R \hspace{1 mm} \sin{(\varphi)}, &
 y &= R \hspace{1 mm} \cos{(\varphi)}, &
 z &= Z .
\end{align}
Note here that the angle $\varphi = 0$ corresponds to the Cartesian $y$-axis.
The unit
basis vectors and (covariant) metric tensor are:
\begin{align}
 \ehat_R      &= (\sin{(\varphi)} ,   \cos{(\varphi)},0)^T, &
 \ehat_Z      &= ( 0 ,0 ,1 )^T, &
 \ehat_{\varphi} &= ( \cos{(\varphi)} , -\sin{(\varphi)} , 0 )^T,
\\
    (g_{ij}) &= \begin{pmatrix}
  1 & 0 & 0 \\
  0 & 1 & 0 \\
  0 & 0 & R^2
   \end{pmatrix}
% \vn R &= (\sin{(\varphi)} ,   \cos{(\varphi)},0 )^T , &
%  \vnZ &= ( 0 ,0 ,1 )^T,  &
%  \vn{\varphi} &= \frac{1}{R} ( \cos{(\varphi)} , -\sin{(\varphi)} , 0 )^T .
\end{align}
With the help of the metric elements we get a well behaved volume element \(\sqrt{g} = R\). However, we have a coordinate singularity at \(R=0\).
The cylindrical coordinate basis vectors are mutually orthogonal to each other.

\subsection{The flux function}
In cylindrical coordinates the general axisymmetric  magnetic field can be written as (dimensionless)
\begin{align}
 \vec{B} &= \frac{R_0}{R}\left[I(\psi_p) \ehat_{\varphi} + \frac{\partial
 \psi_p}{\partial Z} \ehat_R -  \frac{\partial \psi_p}{\partial R} \ehat_Z\right] ,
\end{align}
which can obviously not be manipulated to be in Clebsch form.
Hence we are dealing with a non-flux aligned coordinate system.
For the sake of clarity we define the poloidal magnetic field \( \vec{B}_p = \frac{R_0}{R}\left( \frac{\partial \psi_p}{\partial Z}\ehat_R - \frac{\partial \psi_p}{\partial R}\ehat_Z\right)
\) and the toroidal magnetic field \(\vec{B}_t =\frac{R_0I}{R} \ehat_{\varphi}\).
\begin{tcolorbox}[title=Note]
With a typically convex function $\psi_p$ (second derivative is
positive), $I(\psi_p)>0$ and the previously defined coordinate system the field
line winding is a {\bf left handed screw} in the positive $\ehat_\varphi$-direction.
Also note that then $\vec B\times\vn\vec B$ points {\bf down}, towards the magnetic X-point,
and we have the {\bf favourable} drift direction (in experiments H-mode
is reached easier in this configuration).
\end{tcolorbox}

We scaled $R$, $Z$ and $R_0$ with $\rho_s = \sqrt{T_e m_i}/(eB_0)$, the
magnetic field with $B_0$, the poloidal flux with $\psi_{p0} = B_0\rho_s \hat
R_0$ and the poloidal equilibrium current streamfunction with $I_0 = B_0 \hat R_0$ (with $\hat R_0 =
\rho_s R_0$ the dimensional major radius).
\subsubsection{Solov'ev equilbrium}\label{sec:solovev}

We have the equilibrium equations in toroidally symmetric, ideal MHD
$\vn p = \vec j\times \vec B$ and $\vn\times\vec B = \beta \vec j$ normalized with $p_0 = n_0 T_0$, and $j_0 = e n_0 c_S$, where we introduce $\beta = n_0 T_0 \mu_0 /B_0^2$.
Note that this normalization is in line with the one later chosen for the gyrofluid
equations but is unnatural for the MHD type equilibrium equations through the introduction
of $\rho_s$ and $\beta$.
\begin{align}
    \vn\times \vec B &= \frac{R_0}{R}\left[ -\Delta^*\psi_p\ehat_\varphi + I_Z \ehat_R - I_R\ehat_Z \right]\equiv \beta \vec j\\
 \beta j_\parallel &= \beta \vec j\cdot \bhat = \beta \frac{\d p}{\d\psi_p} \frac{I(\psi_p)}{B} +
 \frac{\d I}{\d\psi_p} B \quad \text{  Pfirsch-Schl\"uter \& Bootstrap current } \\
 \beta \vec j_\perp &= \beta \bhat\times\left(\vec j\times\bhat\right)=
 \beta \frac{\bhat \times \vn p}{B} \quad\quad\quad \text{ diamagnetic current} \\
 \beta \vec j\times\vec B &= \frac{R_0^2}{R^2}\left[ -\Delta^* \psi_p - I
     \frac{\d I}{\d \psi_p} \right]\vn\psi_p \equiv \beta \frac{\d p}{\d\psi_p}\vn\psi_p =\beta \vn p
\end{align}
from where we recover the Grad-Shafranov equation
\begin{align}\label{eq:GSEdimless}
    -\Delta^*_\perp  \psi_p &= \beta \frac{R^2}{R_0^2} \frac{d p}{d  \psi_p } + I \frac{d I}{d  \psi_p } \equiv \beta \frac{R}{R_0} j_{\hat\varphi}
\end{align}
with $\Delta^*_\perp \psi_p = R\partial_R (R^{-1}\psi_R) + \psi_{ZZ}$.
The Solov'ev assumptions consist of \(A/R_0 = -I \frac{d I}{d  \psi_p }\) and \((1-A)/R_0 = -\frac{d p}{d  \psi_p }\), where \(A\) is a constant~\cite{Cerfon2010,Cerfon2014}.
By integration over \(\psi_p\) we find
$
p(\psi_p) = (A-1)\psi_p/R_0/\beta + p(0)$, %Does that mean that psi_p has to be negative if A=0?
 $I(\psi_p) = \sqrt{-2 A \psi_p/R_0 + 1}$,
 and
    $j_{\hat\varphi} = \left[(A-1)R^2/R_0^2 - A \right]/R/\beta $.
Note that if $\psi_p$, $I(\psi)$ and $p(\psi)$ are a solution to Eq.~\eqref{eq:GSEdimless}
then so are $\mathcal P_\psi \psi_p$ , $\mathcal P_\psi I(\psi_p)$ and $\mathcal P_\psi^2 p(\psi_p)$.
Also note that for $A=0$ the constant current $I$ becomes arbitrary $\mathcal P_I$.

We introduce \(\bar{R} \equiv \frac{R}{R_0}\) and \(\bar{Z} \equiv\frac{Z}{R_0}\)
and thus represent a general solution to Equation~\eqref{eq:GSEdimless} as~\cite{Cerfon2010}
\begin{subequations}
\label{eq:solovev}
\begin{align}
 \psi_p (R,Z) &= \mathcal P_{\psi} R_0 \left[ A\left( \frac{1}{2} \bar{R}^2 \ln{\bar{R}}
   - \frac{1}{8}\bar{R}^4\right)+ \frac{1}{8}\bar{R}^4
   + \sum_{i=1}^{12} c_{i}  \bar{\psi}_{pi}\right],\\
   I(\psi_p) &= \mathcal P_I\sqrt{ - 2A\frac{\psi_p}{R_0\mathcal P_{\psi}} +1},
\end{align}
\end{subequations}
with $\mathcal P_\psi$ a free constant, $\mathcal P_I = \pm \mathcal P_\psi$ for $A\neq 0$ and $\mathcal P_I$ arbitrary for $A=0$ (purely toroidal equilibrium current).
We have
\begin{align}
    p(\psi_p) = \mathcal P_\psi \frac{( A-1)\psi_p}{\beta R_0 } + p(0) \qquad
    j_{\hat\varphi} = \frac{\mathcal P_\psi}{\beta } \left[\frac{(A-1)R}{R_0^2} - \frac{A}{R}\right]
\end{align}
\rowcolors{2}{gray!25}{white}
\begin{longtable}{>{\RaggedRight}p{7cm}>{\RaggedRight}p{7cm}}
\toprule
  $\bar{\psi}_{p1}=1$
  & $\bar{\psi}_{p7}=8\bar{Z}^6 -140 \bar{R}^2 \bar{Z}^4
                      + 75 \bar{R}^4 \bar{Z}^2 - 15\bar{R}^6\ln{\bar{R}}+ 180 \bar{R}^4 \bar{Z}^2 \ln{\bar{R}} \
                       -120 \bar{R}^2 \bar{Z}^4 \ln{\bar{R}}$\\
%
  $\bar{\psi}_{p2}=\bar{R}^2$ &
  $\bar{\psi}_{p8}=\bar{Z}$ \\
%
  $\bar{\psi}_{p3}=\bar{Z}^2 - \bar{R}^2 \ln{\bar{R}}$ &
  $\bar{\psi}_{p9}=\bar{Z}  \bar{R}^2$\\
%
  $\bar{\psi}_{p4}=\bar{R}^4 -4\bar{R}^2\bar{Z}^2$ &
  $\bar{\psi}_{p10}=\bar{Z}^3 - 3 \bar{Z} \bar{R}^2 \ln{\bar{R}}$\\
  %
  $\bar{\psi}_{p5}=2\bar{Z}^4 - 9 \bar{R}^2\bar{Z}^2 + \
                     3 \bar{R}^4 \ln{\bar{R}} \
                    -12  \bar{R}^2\bar{Z}^2 \ln{\bar{R}}$
  &
$\bar{\psi}_{p11}=3 \bar{Z}\bar{R}^4 - 4\bar{Z}^3\bar{R}^2$\\
%
  $\bar{\psi}_{p6}=\bar{R}^6 -12 \bar{R}^4 \bar{Z}^2
                     + 8  \bar{R}^2 \bar{Z}^4$ &
  $\bar{\psi}_{p12}= 8 \bar{Z}^5 -45 \bar{Z} \bar{R}^4 - \
                       80 \bar{Z}^3 \bar{R}^2\ln{\bar{R}} \
                       +60 \bar{Z} \bar{R}^4\ln{\bar{R}}$ \\
   & \\
\bottomrule
\end{longtable}

\subsubsection{Polynomial expansion}
As an alternative and in order to better fit experimental equilibria we offer
a polynomial expansion of the magnetic flux function
\begin{subequations}
\label{eq:polynomial}
\begin{align}
    \psi_p(R,Z) &= \mathcal P_\psi R_0\sum_{i=0}^{N_R-1}\sum_{j=0}^{N_Z-1} c_{ij}\bar R^i\bar Z^j\\
   I(\psi_p) &= \mathcal P_I
\end{align}
\end{subequations}
where the number of polynomial coefficients $N_R$ and $N_Z$ can be freely chosen.
\subsubsection{Discussion}
Since Eqs.~\eqref{eq:solovev} and \eqref{eq:polynomial} are given analytically we can numerically evaluate $\psi_p$ and $I$
and all their derivatives
at arbitrary points to machine precision, which is simple to implement and fast to execute.
This translates to an exact representation of the magnetic field and related
quantities like the curvature operators in code. In particular,
the X-point and O-point can be determined to machine
precision via a few Newton iterations.

The choice of the coefficients \(c_{i}\) and \(A\), respectively $c_{ij}$ determines the actual form
of the magnetic field.
We can for example represent single and asymmetric double X-point configurations, force-free states,
field reversed configurations and low and high beta tokamak equilibria.
$R_0$ appears as an artificial scaling factor
(note here that a change in $\rho_s$ changes $R_0$ but not the form or size of
the dimensional equilibrium magnetic field).
The scaling factors $\mathcal P_\psi$ and $\mathcal P_I$ are mainly introduced to maximize the flexibility e.g. to adapt the solution to experimental equilibria or to reverse the sign of the magnetic field.
If an X-point is present, we choose $c_1$ such that
$\psi_p(R_X, Z_X) = 0$ that is the separatrix is given by $\psi_p(R,Z) = 0$.

\subsection{Curvature operators and perpendicular Poisson bracket}
Note that
\begin{align}
    B^R&=B_R = R_0\psi_Z/R \\
    B^Z&=B_Z = - R_0\psi_R/R \\
    B^\varphi &= B_\varphi/R^2 = R_0I/R^2
\end{align}
(contra- and covariant components of $\vec B$).
By construction we have $\partial_\varphi B = 0$ with
\begin{align}
  B = \frac{R_0}{R}\sqrt{ {I^2 + |\vn \psi_p|^2}}.
    \label{}
\end{align}
Furthermore, we have
\begin{align}
  \npar f(R,Z) = \frac{R_0}{RB}[f,\psi_p]_{RZ}\Rightarrow \npar \ln B = \frac{R_0}{RB^2}\left[B, \psi_p\right]_{RZ} = -\vec\nc\bhat.
\end{align}
We allow various simplifications to the curvature operator
for the Solov'ev equilibrium.

%%%%%%%%%%%%%%%%%%%%%%%%%

\subsubsection{Toroidal (and negative toroidal) field line approximation}\label{sec:torfieldlineapprox}
The toroidal/negative toroidal field line approximation applies \(\bhat\approx \pm \ehat_\varphi\) to all perpendicular operators
(e.g.: Poisson bracket, perpendicular elliptic operator and curvature operators)
but retains the full expression for the magnetic field unit vector \(\bhat\)
for parallel operators (\(\npar\) and \(\Delta_\parallel\)).
\begin{tcolorbox}[title=Note]
We allow the negative sign $-\ehat_\varphi$ to enable a sign reversal of the magnetic field, see Section~\ref{sec:field_reversal}.
\end{tcolorbox}
In cylindrical coordinates that is
\begin{align}
[f,g]_\perp \equiv [f,g]_{RZ} &= \pm\frac{1}{R} \left(\partial_R f\partial_Z g - \partial_Z f\partial_R g\right) \\
\np f &= \partial_R f \ehat_R + \partial_Z f \ehat_Z \\
\Delta_\perp f &= \frac{1}{R}\partial_R \left( R \partial_R f\right) + \partial_Z(\partial_Z f)
\label{}
\end{align}
The curl of $\bhat$ reduces to
%\begin{align}
 $\vn\times\bhat \approx -  \frac{\pm 1}{R} \ehat_Z$.
%end{align}
This simplifies the curvature operators to:
\begin{align}
\vec{{K}}_{{\vn\times\bhat}}  &\approx  -  \frac{\pm 1}{B R} \ehat_Z , &
\vec{ {K} }_{\vn  B}  &\approx  -\frac{\pm 1}{B^2}\frac{\partial B}{\partial Z}\ehat_R +\frac{\pm 1}{B^2} \frac{\partial B}{\partial R}\ehat_Z &
%\ehat_\varphi \times \vn B, &
\vec{ {K} } &\approx \vec{ {K} }_{\vn  B}  +\vec{ {K} }_{{\vn\times\bhat}} ,
%\\
%\mathcal{K}_{{\vn\times\bhat}}(f)   &\approx  -  \frac{1}{B R} \frac{\partial f}{\partial Z},&
%\mathcal{K}_{\vn  B} (f)  &= \frac{1}{B} \left[\ln B, f \right]_{RZ},&
%\mathcal{K} (f) &\approx\frac{1}{B} \left[\ln B, f \right]_{RZ}-  \frac{1}{B R} \frac{\partial f}{\partial Z} ,
\end{align}
and
\begin{align}
 \nc \vec{{K}}_{{\vn\times\bhat}} &\approx \frac{\pm 1}{R B^2} \frac{\partial B}{\partial Z},
\end{align}
which results in a vanishing divergence of the curvature operators \( \nc \vec{ {K} } = 0\).

Note that in an actual toroidal field we have
\begin{align}
  \vec B(R) := \pm \frac{R_0}{R} \ehat_\varphi
  \label{}
\end{align}
We then have $\bhat = \pm\ehat_\varphi$ and the curvature operators further
simplify to
\begin{align}
  \vec{  K_{\vn\times\bhat}} = \vec{  K_{\vn B}} = -\frac{\pm 1}{R_0} \ehat_Z =
\vec{  K}/2\\
  \nc\vec{ K_{{\vn\times\bhat}}}=
    \npar \ln B = 0
    \label{}
\end{align}
Note: the negative sign is automatically chosen in code if $I(R_0, 0)<0$.

\subsubsection{Low beta approximation}\label{sec:lowbetaapprox}
In this approximation we apply the toroidal field line approximation
as in Section
\ref{sec:torfieldlineapprox}
but approximate the curvature operator $ \vec K_{\vn\times\bhat} \approx \bhat\times\vec \kappa$
  with
  $\vec \kappa := \bhat \cn\bhat = -\bhat \times( \vn\times \bhat)$.
For an isotropic pressure plasma \(\vec{P} = \vec{I} P_\perp + \vec{b} \vec{b} P_\Delta \approx \vec{I} P_\perp\) and with the definition of the plasma beta parameter
\(\beta = \frac{P}{B^2/(2 \mu_0) } \)
we can rewrite the curvature to
\begin{align}
    \vec{\kappa} &\approx \frac{\beta}{2} \vn \ln(P) +\np \ln{B} .
\end{align}
In low beta plasmas \(\beta\ll1\) the curvature reduces to:
\begin{align}
    \vec{\kappa} & \approx \np \ln{B} .
\end{align}
This simplifies the curvature operators to:
\begin{align}
\vec{{K}_{{\vn\times\bhat}}} \approx
\vec{ {K} }_{\vn  B}  &\approx  -\frac{1}{B^2}\frac{\partial B}{\partial Z}\ehat_R +\frac{1}{B^2} \frac{\partial B}{\partial R}\ehat_Z &
{K} (f) &\approx 2{K}_{\vn  B} (f) , &
    \vn\times\bhat \cdot \vec{{K}}_{\vn  B} &= 0.
\end{align}
The divergence over the curvature vanishes \( \nc \vec{ {K} } = 0\) only if \( \nc \vec{ {K}}_{\vn  B}   = 0\).
In general, the divergence \( \nc \vec{ {K} } \approx 0\) is only approximately vanishing.
\subsubsection{True perpendicular terms}

Without any approximations we have
\begin{align}
b^R = {\frac{\partial \psi}{\partial Z}}\left(I^2+|\vn\psi|^2\right)^{-1/2} \quad
b^Z = -{\frac{\partial \psi}{\partial R}}\left(I^2+|\vn\psi|^2\right)^{-1/2} \quad
b^\varphi = \frac{I}{R}\left(I^2+|\vn\psi|^2\right)^{-1/2} \\
\vec\nc\bhat = -\npar \ln B = -\frac{R_0}{R B^2}[B,\psi_p]_{RZ} \\
\left({\vn\times\bhat}\right) \cdot\bhat =
    (I'(\vn\psi_p)^2 - I \Delta_\perp^* \psi_p)\frac{ R_0^2}{R^2B^2} \propto 1/R_0
\label{}
\end{align}
where for the last
estimate we inserted the Grad-Shafranov equation and the Solov'ev assumptions.
We can then insert $\bhat$ into the exact definitions for $[.,.]_\perp$, $\np$ and $\Delta_\perp$ from Section~\ref{sec:magnetic}.

For the curvature terms we can explicitly write
\begin{align}
K_{\vn B}^R &= -\frac{R_0 I}{B^3R}\frac{\partial B}{\partial Z} \equiv -\frac{1}{B^2}\frac{\partial B}{\partial Z}b^\varphi \\
K_{\vn B}^Z &= \frac{R_0 I}{B^3R}\frac{\partial B}{\partial R}\equiv \frac{1}{B^2}\frac{\partial B}{\partial R}b^\varphi \\
K_{\vn B}^\varphi &= \frac{R_0}{B^3R^2}\left(
      \frac{\partial \psi}{\partial Z} \frac{\partial B}{\partial Z}
    + \frac{\partial \psi}{\partial R}\frac{\partial B}{\partial R}\right)
%\equiv \frac{1}{B^2R}\left(\bhat^R \frac{\partial B}{\partial Z} - \bhat^Z \frac{\partial B}{\partial R}\right)\quad %contravariant phi component
\label{}
\end{align}
and
\begin{align}
K_{\vn\times\bhat}^R &= \frac{R_0 }{RB^3}\left( B\frac{\partial I}{\partial Z} -I\frac{\partial B}{\partial Z}\right) \\
K_{\vn\times\bhat}^Z &= \frac{R_0 }{RB^3} \left( I\frac{\partial B}{\partial R} - B\frac{\partial I}{\partial R} \right)\\
K_{\vn\times\bhat}^\varphi &= \frac{R_0}{R^2B^2}\left(
+ \frac{1}{B}\frac{\partial\psi}{\partial Z} \frac{\partial B}{\partial Z}
+ \frac{1}{B}\frac{\partial \psi}{\partial R}\frac{\partial B}{\partial R}
-R\frac{\partial}{\partial R}\left(\frac{1}{R}\frac{\partial\psi}{\partial R}\right)
- \frac{\partial^2 \psi}{\partial Z^2}
\right) \\
\vec\nc\vec{\mathcal K_{\vn\times\bhat}} &= -\vec\nc\vec{\mathcal K_{\vn B}}=
    -\vec{\mathcal K_{\vn\times\bhat}}\cn\ln B = \frac{R_0}{RB^3}[I,B]_{RZ}
%contravariant phi component
\label{}
\end{align}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Flux surface averaging and safety factor}
\subsubsection{Preliminary}
Recall that the {\bf Dirac delta-function} has the property (in any dimension):
\begin{align} \label{eq:dirac_delta}
\int_V f(\vec x) \delta(h(\vec x) - h') \dV = \int_{h=h'} \frac{f(\vec x)}{|\vn h|} \dA
\end{align}
which means that the delta-function can be used to express area integrals of the
submanifold given as a contour of the function $h(\vec x)$.
A numerically tractable approximation to the delta-function reads
\begin{align}\label{eq:delta}
\delta(h(\vec x)-h') = \frac{1}{2\pi \epsilon^2}
\exp\left( - \frac{\left(h(\vec x)-h'\right)^2}{2\epsilon^2}\right)
\end{align}
where $\epsilon$ is a small, free parameter.
In the DG framework the left-hand side
of Eq.~\eqref{eq:dirac_delta} can thus readily be computed
via Gauss-Legendre quadrature, which we propse as a first method to compute area
integrals even if our coordinate system is not aligned to the area.
Note: in order for this to work the Delta function needs to be numerically
resolved and cannot be made arbitrarily small.
This introduces a smoothing effect
over neighboring contour lines which is given by the grid distance.

Furthermore, recall the {\bf co-area formula}
\begin{align} \label{eq:coarea}
\int_{\Omega_0} f(\vec x) \dV =
\int_0^{h_0} \left( \int_{h=h'} \frac{f(\vec x)}{|\vn h|}  \dA  \right) \d h'
\end{align}
where $\Omega_0$ is the volume enclosed by the contour $h=h_0$.
The co-area formula can be viewed as a change of variables in the
volume integral.

We define the {\bf toroidal average} of a function $f(R,Z,\varphi)$ as
\begin{align} \label{eq:phi_average}
\PA{ f}(R,Z) := \frac{1}{2\pi}\oint f(R,Z,\varphi)\d \varphi
\end{align}

In arbitrary coordinates the area integral is defined by the pull back
of the flux 2-form and the metric
\begin{align}
\label{}
\dA^2 = i_{\hat \psi_p} vol^3 \quad \hat \psi_p = \frac{\vn \psi_p}{|\vn \psi_p|}
\end{align}
to a parameterization of the flux-surface.
In a flux-aligned coordinate system $\{\zeta, \eta, \varphi\}$ the pull-back is trivial ($\zeta=const$) and we have
\begin{align}
\dA &= \sqrt{g^{\zeta\zeta}} \sqrt{g} \d\eta\d\varphi = f_0|\vn\psi_p|\sqrt{g}\d\eta\d\varphi,
\\
\vec\dA &:= \hat\psi_p \dA = f_0 (\vn\psi_p) \sqrt{g}\d\eta\d\varphi,\quad
\label{}
\end{align}
where we used that $g^{\zeta\zeta} = (\vn\zeta)^2 = f_0^2(\vn\psi_p)^2$.
Notice that numerically we can integrate in flux-aligned coordinates by generating a corresponding
grid and pulling back (interpolating) the relevant fields to this grid. This is the second method
to numerically compute area integrals.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Flux surface average}

The flux surface average (as a {\bf volume average} after \cite{haeseleer}) is defined as an average over a
small volume - a shell centered around the flux-surface - defined by two neighboring flux-surfaces.
With the help of the volume
flux label (notice that both the volume $v$ as well as the poloidal flux $\psi_p$ have physical
meaning while the coordinate $\zeta(\psi_p)$ is an arbitrary choice) we define
\begin{align} \label{eq:fsa_vol}
v(\psi_p) :=& \int_{\psi_{p,O}}^\psi \dV = \int^{\zeta(\psi_p)} \sqrt{g}\d\zeta\d\eta\d\varphi,
\\
\frac{\d v}{\d\psi_p} =& \int\dA |\vn\psi_p|^{-1} = 2\pi f_0\oint_{\zeta(\psi_p)} \sqrt{g}\d\eta \\
\RA{ f }_\psi :=& \frac{\partial}{\partial v} \int \dV f
 = \frac{1}{\int \dA |\vn\psi_p|^{-1} } \int_{\psi_p} \frac{f(\vec x)}{|\vn\psi_p|} \dA \nonumber\\
=& \frac{\int_\Omega \PA{ f}(R,Z) \delta(\psi_p(R,Z)-\psi_{p})H(Z-Z_X)\ R \d R \d Z}
{\int_\Omega \delta(\psi_p(R,Z)-\psi_{p})H(Z-Z_X)\ R \d R \d Z}\nonumber\\
 =& \left(\frac{\d v}{\d\psi_p }\right)^{-1} 2\pi f_0 \oint_0^{2\pi} \PA{ f}(\zeta,\eta) \sqrt{g}\d\eta
 = \frac{1}{\oint \sqrt{g}\d\eta } \oint_0^{2\pi} \PA{ f}(\zeta,\eta) \sqrt{g}\d\eta
\end{align}
where we used the co-area formula Eq.~\eqref{eq:coarea} for the second identity
and we use the Heaviside function $H(Z-Z_X)$ to cut away contributions from below the X-point
in our domain $\Omega$.
 We immediately see that this definition is particularly easy to compute
 in a flux-aligned coordinate system. Notice however that the volume element
 does appear (unlike e.g. Tokam3X papers).
 We use our grid construction algorithm with constant monitor metric described in Reference~\cite{Wiesenberger2018} to construct a flux-aligned grid and interpolate
 the values of any function onto its grid points.
 Even though this grid is unusable for simulations due to the diverging metric at the X-point the
 evaluation of integrals works well as the singularity is integrable.

The flux-surface average fulfills the basic identities
\begin{align}
\label{eq:fsa_identities}
\RA{ \mu f + \lambda g} &= \mu\RA{ f} + \lambda \RA{ g} \\
\RA{ f(\psi_p)} &= f(\psi_p)
\end{align}

The volume average is well-suited for density-like quantities
as we can see with the following identity.
Assume we have a quantity $X$ with $\partial_t X + \nc \vec j_X = \Lambda_X$.
Then we can use the volume average to write
\begin{align}
\frac{\partial}{\partial t} \RA{X } + \frac{\partial}{
  \partial v} \RA{ \vec j_X\cn v}  = \RA{ \Lambda_X}
\label{eq:fsa_balance}
\end{align}
where again $v=v(\psi_p)$ is the volume flux label.
The {\bf total flux} of a given flux density $\vec j_X$ through the
flux surface $\psi_p = \psi_{p0}$ is given by
\begin{align}
\RA{\vec j_X\cn v} &:= J_X=\oint_{\psi_p=\psi_{p0}} \vec j_X\cdot \vec{\dA} =
 \frac{\d v}{\d\psi_p} \RA{ \vec j_X\cn\psi_p }\\
 &=
   2\pi f_0 \oint_0^{2\pi} \PA{ \vec j_X\cn\psi_p}(\zeta,\eta) \sqrt{g}\d\eta
%2\pi\int_\Omega \vec \PA{ \vec j\cn\psi_p} \delta(\psi_p(R,Z)-\psi_{p0}) H(Z-Z_X)\ R \d R \d Z
\label{eq:total_flux}
\end{align}
Once we have the flux-surface averaged equation we can easily get the volume integrated version (again with the help of the co-area formula)
\begin{align}
\frac{\partial}{\partial t} \int_0^{v(\psi_p)}\RA{X} \d v
+ \RA{ \vec j_X\cn v}(v(\psi_p))  = \int_0^{v(\psi_p)}\RA{ \Lambda_X}\d v
\label{eq:integral_balance}
\end{align}

\subsubsection{The safety factor}
Assume that we pick a random field line and follow it (integrate it) for exactly one
poloidal turn. The {\bf safety factor} is defined as the ratio between
the resulting toroidal angle ($\Delta\varphi$) to the poloidal angle ($2\pi$)
\begin{align}
q := \frac{\Delta\varphi}{2\pi}
\label{}
\end{align}
Since our magnetic field is symmetric in $\varphi$ and we used one
full poloidal turn this definition is independent of which
fieldline we pick on a given flux surface.

%We define the poloidal length $s$ as the fieldline following
%parameter i.e. $\vec B\cn s \equiv B_p = R_0|\vn \psi_p|/R$
%and $\d\varphi/\d s = B^\varphi(R(s), Z(s)) / B_p(R(s),Z(s))$.
%We can then express the safety factor as the line integral
%\begin{align}
%q=\frac{1}{2\pi}\oint \frac{B^\varphi}{B_p} \d s = \frac{1}{2\pi}\oint_{\psi_p=\psi_{p0}}\frac{I(\psi_p)}{R|\vn\psi_p|} \d s
%= \frac{1}{2\pi}\int \frac{I(\psi_p)}{R}\delta(\psi_p-\psi_{p0}) H(Z-Z_X) \d R\d Z
%\end{align}
%where we made use of Eq.~\eqref{eq:dirac_delta} in two dimensions in the
%last equality and thus arrive at a numerical tractable expression
%to evaluate the safety factor.
We define the geometric poloidal angle $\Theta$ as the fieldline following
parameter i.e. $\vec B\cn\Theta = R_0(\psi_R (R-R_0) + \psi_Z Z)/r^2R$.
We can then directly integrate the safety factor as
\begin{align}\label{eq:safety_factor}
\frac{\d R}{\d\Theta} = \frac{B^R}{B^\Theta}\quad
\frac{\d Z}{\d\Theta} = \frac{B^Z}{B^\Theta}\quad
\frac{\d \varphi}{\d\Theta} = \frac{B^\varphi}{B^\Theta}\\
q\equiv\frac{1}{2\pi}\oint \frac{B^\varphi}{B^\Theta} \d\Theta
\end{align}
We integrate this equation with the help of one of our ODE integrators, i.e. we use a high-order Runge-Kutta method
and refine the stepsize until machine-precision is reached.
Notice that the safety factor diverges on the last closed flux
surface whereas Eq.~\eqref{eq:total_flux}
remains finite due to the $\vn\psi_p$ factor.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Toroidal averages}
Here, we comment on the $\varphi$ average that is part of the flux-surface average Eq.~\eqref{eq:fsa_vol}.
One simple approach is
quadrature of the form
\begin{align}\label{eq:toroidal_summation}
    \bar f = \frac{1}{N} \sum_{i=0}^{N-1} f_i (R,Z)
\end{align}
where $N=32$ in most of our simulations and $f_i$ is the $i$-th toroidal plane.
Since the boundary conditions in $\varphi$ are periodic this amounts to the trapezoidal rule.
A low number of toroidal planes is sufficient in simulations when we use the toroidal field
approximation in combination with the
flux-coordinate independent (FCI) approach for the parallel derivatives.
However, since the actual $\varphi$ direction is
under-resolved the
integration gives a wrong answer to the actual $\varphi$ average (seen in 2d plots as little humps).
This is because the resulting structures are predominantly field aligned and not toroidally symmetric.

In order to improve the toroidal average we now have the following idea:
if we, before we do the $\varphi$ integration,
interpolate the function to integrate onto a large number of toroidal
planes then the result should
be more accurate than before.
In other words we interpolate the function given on the coarse $\varphi$ simulation grid
onto a hypothetic fine $\varphi$ grid along the magnetic field lines
and only then compute the $\varphi$ average.

Let us divide the $\varphi$ direction between two original planes into $N_\varphi+1$ (a large number) equidistant planes
of distance $\delta \varphi$ and integrate the magnetic field $\vec B$ in between.
\begin{subequations}
\begin{align}
    \frac{\d R}{\d\varphi}&= \frac{B^R}{B^\varphi},\\ %\frac{R}{I}\frac{\partial\psi}{\partial Z},\\
    \frac{\d Z}{\d\varphi}&=\frac{B^Z}{B^\varphi},\\%-\frac{R}{I}\frac{\partial\psi}{\partial R}.
\end{align}
\label{eq:fieldline}
\end{subequations}
We integrate Eqs.~\eqref{eq:fieldline} from $\varphi=0$ to $\varphi=\pm \Delta \varphi$
with initial condition
\begin{align}
    (R(0), Z(0) ) = (R, Z).
    \label{}
\end{align}
Let us characterize the solution $(R(\pm \delta \varphi), Z(\pm \delta \varphi))$ to Eqs.~\eqref{eq:fieldline} as the flow generated by $\vec B/B^\varphi$
\begin{align}
    \Tdpm\vec z \equiv \Tdpm[R, Z, \varphi]:= ( R(\pm \delta\varphi), Z( \pm \delta\varphi), \varphi\pm\delta \varphi),
    \label{}
\end{align}
Obviously we have $\Tdm\circ\Tdp = 1$, but $\Tdpm$ is not necessarily unitary since $\vec B/B^\varphi$ is in general
not divergence free.
We are now able to extend the function $f$ given on the coarse $\varphi$ grid unto the fine $\varphi$ grid via
\begin{align}
    f(R,Z,\varphi_0+j\delta\varphi) = {\Tdm}^j f(R,Z,\varphi_0)\\
    f(R,Z,\varphi_0-j\delta \varphi) = {\Tdp}^j f(R,Z,\varphi_0)
\end{align}
This gives simple 0-th order extrapolation of our function.
Let us call $f_i := f(R,Z,\varphi_i)$ the $i$-th toroidal plane and $N_\varphi$ even. Then
we have the following integration, where we consider the original toroidal planes as cell-centered
\begin{align}
    \RA{f}_\varphi &= \frac{1}{(N_\varphi+1) N} \left[\left(
    {\Tdp}^{N_\varphi/2} f_0 + ... + \Tdp f_0 + f_0 + \Tdm f_0 ... + {\Tdm}^{N_\varphi/2} f_0\right)\right. \nonumber\\
    &\left. +\left( {\Tdp}^{N_\varphi/2} f_1 + ... + \Tdp f_1 + f_1 + \Tdm f_1 ... + {\Tdm}^{N_\varphi/2} f_1\right)  + ... \right] \nonumber\\
    &= \frac{1}{N (N_\varphi+1)} \sum_{i=0}^{N-1} \left[f_i + \sum_{j=1}^{N_\varphi/2} \left( {\Tdm}^j f_i + {\Tdp}^jf_i\right)\right] \nonumber\\
    &=
    \frac{1}{N_\varphi+1} \left[ \sum_{j=0}^{N_\varphi/2}  {\Tdm}^j \left(\frac{1}{N}\sum_{i=0}^{N} f_i\right)
    +
    \sum_{j=1}^{N_\varphi/2}  {\Tdp}^j \left(\frac{1}{N}\sum_{i=0}^{N} f_i\right)\right]
    \nonumber\\
    &=
    \frac{1}{N_\varphi+1} \left[ \sum_{j=0}^{N_\varphi/2}  {\Tdm}^j \bar f(R,Z)
    +
    \sum_{j=1}^{N_\varphi/2}  {\Tdp}^j \bar f(R,Z)\right]
\end{align}
Here, we used that the push-forward operator $\Tdm$ is linear that is $\Tdm f_0 + \Tdm f_1 = \Tdm (f_0+f_1)$
and recover the simple toroidal summation $\bar f$ Eq.~\eqref{eq:toroidal_summation}.
Now, we can see that in the limit $N_\varphi \rightarrow\infty$ the discrete sum represents the integral
of the form
\begin{align}
    \RA{f}_\varphi(R,Z) = \frac{1}{\Delta\varphi}\int_{-\Delta\varphi/2}^{\Delta\varphi/2}\d\varphi \bar f(R(\varphi),Z(\varphi))
\end{align}
A consistency test of this approach is to simply use $\vec B = e_\varphi$. Then
$\Tdpm = 1$ and we recover the original integration $\RA{f}_\varphi= \bar f$.
Now, instead of doing a 0-th order interpolation let us try a linear interpolation along field-lines in between planes that is ( assuming $N_\varphi$ toroidal planes)
\begin{align}
    f(R,Z,\varphi_i + j\delta\varphi) = \left(1-\frac{j}{N_\varphi}\right){\Tdm}^j f_i + \frac{j}{N_\varphi} {\Tdp}^{N_\varphi -j}f_{i+1}
\end{align}
\begin{align}
    \RA{ f}_\varphi &= \frac{1}{N_\varphi N} (( f_0 + (1-\alpha_1)\Tdm f_0 + \alpha_1 (\Tdp)^{N_\varphi -1} f_1 + (1-\alpha_2)(\Tdm)^2 f_0 + \alpha_2 (\Tdp)^{N_\varphi-2} f_1 ...  )+ (f_1 + ...) + ...)\nonumber\\
    &= \frac{1}{ N_\varphi} \sum_{j=0}^{N_\varphi-1}  (1-\alpha_j)(\Tdm)^j \bar f+\alpha_j (\Tdp)^{N_\varphi -j} \bar f
    = \frac{1}{\Delta\varphi}\int_{-\Delta\varphi}^{\Delta\varphi}\d\varphi w(\varphi) \bar f (R(\varphi),Z(\varphi))
    \label{eq:cta}
\end{align}
with $\alpha_j = \frac{j}{N_\varphi}$ and $w(\varphi)$ a linear weight function (pyramid shape) with $\int_{-\Delta\varphi}^{\Delta\varphi} w(\varphi) = \Delta\varphi$. Taking $\Tdpm=1$ again leads to the old result.

Now, an interesting question is, what happens if we are trying to apply the above
results to a function that is not field-aligned like $B(R,Z)$ of $\vec K\cn\psi_p$ for instance? For those functions $\bar f_\mathrm{old}$ actually yields the exact
result, while the convolution is an approximation.
Here, we have to test.
Typically, the functions that we use are slowly varying in $R$ and $Z$ and
so the convolution should not change the result too much.
A good test candidate is still $\langle \mathcal K(\psi_p)\rangle_{\psi_p}=0$.

In all practical tests so far the flux-suface average is not or only very slightly changed by this procedure.
This means that it is not
necessary to follow the smoothing procedure if one is only interested in the flux-surface average.
This makes sense because the toroidal and poloidal averages commute.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Alternative flux labels}
We find the toroidal flux $\psi_t$ by integrating the q-profile $\psi_t = \int^{\psi_p} \d\psi_p q(\psi_p)$. Since $q$ diverges, $\psi_t$, in contrast to $\psi_p$,
is not defined outside the last closed flux-surface (but has a finite value on the last closed flux surface). We now define the normalized poloidal and toroidal flux labels $\rho_p$ and $\rho_t$
\begin{align}
    \rho_p&:= \sqrt{1-\frac{\psi_p }{\psi_{p,O}}} \ \leftrightarrow\ \psi_p = (1-\rho_p^2)\psi_{p,O} \\
    \rho_t&:= \sqrt{\frac{\psi_t}{\psi_{t,\mathrm{sep}}}},\\
    \text{with }\psi_{p,O} &= \psi_p(R_O, Z_O)% \text{ and } \psi_{p,X} = \psi_p(R_X, Z_X)
\end{align}
where $R_O$, $Z_O$ are the coordinates of the O-point.
The labels $\rho_t$ and $\rho_p$ are useful because
equidistant $\rho_p$ and $\rho_t$ values tend to translate to equidistant flux-surfaces
in configuration space.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The model} \label{sec:model}
\subsection{Conservative form}
We scale all spatial lengths by $\rho_s = \sqrt{T_e m_i}/(eB_0)$ and time by the ion gyro-frequency $\Omega_0 = eB_0/m_i$.
The magnetic field is scaled with $B_0$, densities with $n_0$ and the parallel velocity is scaled with $c_s = \sqrt{T_e/m_i}$.
The potential is scaled with $\hat \phi = e/T_e$ and the vector potential with
$\hat A_\parallel = \rho_s B_0$.
We introduce the dimensionless parameters
\begin{align}
  \tau_a = \frac{T_a}{z_aT_e}~,\quad \mu_a = \frac{m_a}{z_am_i}\text{ and }
  \beta:=\frac{\mu_0 n_0 T_e}{B_0^2}
  \label{}
\end{align}
where $a\in\{e,i\}$ is the species label and $z$ is the charge number.
Omitting the species label we arrive at (dividing the density equation by $\Omega_0n_0$ and the velocity equation by $\Omega_0 c_s$)
\begin{tcolorbox}[ams align,
colback=yellow!10!white, colframe=red!50!black,
        highlight math style= {enhanced, %<-- needed for the ’remember’ options
        colframe=red,colback=red!10!white,boxsep=0pt}, title=Model equations
        ]
\frac{\partial}{\partial t} N &+ \vec\nc\left( N \left(
    \vec u_E + \vec u_K + \vec u_{C} + U_\parallel\left(\bhat + {\vec b}_\perp\right)\right)\right) = \Lambda_N + S_N \\
    \mu \frac{\partial}{\partial t} \left(N U_\parallel\right) &+ \mu \nc \left( NU_\parallel \left(
    \vec u_E + \vec u_K + \vec u_{C} + U_\parallel\left(\bhat + {\vec b}_\perp\right)
    \right)\right)  \nonumber \\
    &+ 2\mu \nc ( NU_\parallel \vec u_{\vn\times\bhat})
    -\mu NU_\parallel\nc \vec u_{\vn\times\bhat}
    + \mu NU_\parallel\mathcal K_{\vn\times\bhat}(\psi) \nonumber\\
    =& -\tau \left(\bhat + {\vec b}_\perp\right)\cn N
    -N \left( \left(\bhat+{\vec b}_\perp\right)\cn \psi + \frac{\partial A_\parallel}{\partial t}\right)
    - \eta n_e^2(U_{\parallel,i}-u_{\parallel,e})
    \nonumber\\
    &+ \mu \nu_\parallel \Delta_\parallel U+ \mu N\left(\Lambda_U + S_U\right) + \mu U_\parallel \left(\Lambda_N + S_N\right)
\label{}
\end{tcolorbox}
with
\begin{align}
\vec u_E := \frac{\bhat\times\vn\psi}{B},\quad
\vec u_{K} := \tau \left(\vec{ K_{\vn B}} + \vec{ K_{\vn\times\bhat}}\right)=\tau\vec{ K}  ,\quad  %\nonumber\\
\vec u_C := \mu U_\parallel^2\vec{ K_{\vn\times\bhat}},\nonumber\\
\vec u_{\vn\times\bhat} := \tau\vec{ K_{\vn\times\bhat}},\quad
{\vec b}_\perp = \frac{\vn\times A_\parallel \bhat}{B} = A_\parallel \vec{ K_{\vn\times\bhat}} + \frac{\vn A_\parallel \times \bhat}{B}.
\label{}
\end{align}

The electric potential \(\phi\) and parallel magnetic vector potential \(A_\parallel\) are
computed by the polarisation and induction equations (with $q_e=-e$ and $q_i=+e$)
\begin{align}
 -\nc\left(\frac{\mu_iN_i}{B^2} \np \phi\right) &=  \Gamma_{1,i} N_i -n_e, \quad \Gamma_{1,i}^{-1} := 1-\frac{1}{2}\mu_i\tau_i\Delta_\perp , \\
  -\frac{1}{\beta} \Delta_\perp A_\parallel &= \left(N_i U_{\parallel,i}-n_e u_{\parallel,e} \right)
  \label{eq:polarisation_dimensional}
\end{align}
Given $\phi$ we define the generalised electric potential
\begin{align}
    \psi_e := \phi,\quad \psi_i&:= \Gamma_{1,i} \phi - \frac{\mu_i }{2}\left(\frac{\np\phi}{B}\right)^2
\end{align}
In total
we have an isothermal 3d gyro-fluid model with up to 2nd order FLR effects
on in the electric potential $\phi$ and 0th order FLR effects in the parallel magnetic
potential $A_\parallel$.
We have the continuity equation for the electron density \(n_e\) and the ion gyro-centre
density \(N_i\) and the momentum conservation equation for
the parallel electron velocity \(u_{\parallel,e}\) and the parallel ion gyro-centre velocity \(U_{\parallel,i}\)~\cite{WiesenbergerPhD, HeldPhD}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Diffusive terms}\label{sec:dissres}
Since the gyro-fluid derivation does not include collisional terms we
copied the parallel resistive and viscous terms from the Braginskii fluid equations~\cite{Braginskii1965}.
The electron-ion and ion-ion collision frequencies are given by
$\nu_{ei} = \sqrt{2} z^2 e^4 \ln \Lambda/ (12\pi^{3/2} \sqrt{m_e} \epsilon_0^2) n_e /T_e^{3/2}$, $\nu_{ee} = \nu_{ei}/\sqrt{2}$
and
$\nu_{ii} =  z^4 e^4 \ln \Lambda/ (12\pi^{3/2} \sqrt{m_i} \epsilon_0^2) n_i /T_i^{3/2}$.
We define with the parallel Spitzer resistivity
$\eta_\parallel := \frac{0.51 m_e \nu_{ei}}{n_e e^2}$ and the parallel electron and ion viscosities
$\mu_{\parallel,e}:=0.73\frac{n_eT_e}{\nu_{ei}}$ and $\mu_{\parallel,i} = 0.96\frac{n_iT_i}{\nu_{ii}}$~\cite{Braginskii1965}
\begin{subequations}
\begin{align}
    \eta&:=\frac{en_0\eta_\parallel}{B_0} = \frac{\nu_{ei,0}}{\Omega_{ce}}= 8.45\cdot 10^{-5}\ln \lambda \left(\frac{n_0}{10^{19}\text{m}^3}\right) \left(\frac{T_e}{\text{eV}}\right)^{-3/2} \left(\frac{B_0}{\text{T}}\right)^{-1}, \\
    \nu_{\parallel,e}&:=\frac{\mu_{\parallel,e,0}}{m_e n_0\rho_s^2\Omega_{ci}} = 0.73 \frac{\Omega_{ce}}{\nu_{ei,0}} = \frac{0.73}{\eta} \\
    \nu_{\parallel,i}&:=\frac{\mu_{\parallel,i,0}}{m_i n_0 \rho_s^2\Omega_{ci}} = 0.96 \frac{\Omega_{ci}}{\nu_{ii,0}} = \sqrt{\frac{m_e}{m_i}} \frac{1.36}{\eta}
\end{align}
    \label{eq:resistivity}
\end{subequations}
with $\ln \lambda \approx 10$ and $T_e=T_i$ for the purpose of computing the diffusive coefficients. Note that $\nu_\parallel/N$ represents a kinematic viscosity and is a factor $\sqrt{|\mu_e|}$ smaller for ions than for electrons.
The dynamic viscosity $\mu\nu_\parallel$ is larger for ions than for electrons.
 The approximate Spitzer current \(J_{\parallel,s}:= n_e \left(U_{\parallel,i} - u_{\parallel,e}\right)\)
 determines the parallel resistive terms to $R_\parallel:= n_e\eta J_{\parallel,s}$.

 Note also that since $A_\parallel/\mu_e$ is (potentially) much larger than $u_e$
 it is important that the diffusive operators act on $u_e$ rather than $w_e$.
 The latter essentially would entail that electron diffusion acts on $A_\parallel$.

 For the perpendicular terms we use ad-hoc numerical diffusion terms for numerical
 stabilisation.
\begin{align}
\label{eq:perpdiffNT}
 \Lambda_{n_e} &=  \nu_\perp \Delta_\perp n_e \text{ or } -\nu_\perp \Delta_\perp^2 n_e&
 \Lambda_{N_i} &=  \nu_\perp \Delta_\perp N_i \text{ or } -\nu_\perp \Delta_\perp^2 N_i & \\
 \Lambda_{u_e} &=  \nu_\perp \Delta_\perp u_{\parallel,e} \text{ or } -\nu_\perp \Delta_\perp^2 u_{\parallel,e} &
 \Lambda_{U_i} &=  \nu_\perp \Delta_\perp U_{\parallel,i} \text{ or } -\nu_\perp \Delta_\perp^2 U_{\parallel,i}
\end{align}
Here the mass diffusion coefficient coincides with the viscous coefficient, hence we fixed the Schmidt number \(\mathit{Sc}_\parallel:= \frac{\nu_U}{\nu_N}\) to unity.

We do not derive resistive drifts in the gyro-fluid approach.
The drift-fluid corresponding resistive drift gives an order-of-magnitude estimate for $\nu_\perp$.
We have  $D_i = \rho_i^2 \nu_{ii}$ and $T_{i0} = T_{e0}$.
By dividing by $\rho_s^2 \Omega_{ci}$ we arrive at $\nu_\perp = \nu_{ii0}/\Omega_{ci}$.
\begin{align}
\nu_\perp =
5\cdot 10^{-3} \ln \lambda
\left(\frac{n_0}{10^{19}\text{m}^3}\right)
\left(\frac{T_e}{\text{eV}}\right)^{-3/2}
\left(\frac{B_0}{\text{T}}\right)^{-1}
\left(\frac{m_i}{m_H}\right)^{1/2},
\end{align}

\subsection{Boundary conditions: the penalization method}
We define the simulation box as
$[ R_{\min}, R_{\max}]\times [Z_{\min}, Z_{\max}] \times [0,2\pi]$,
where we define
\begin{align} \label{eq:box}
    R_{\min}&=R_0-\varepsilon_{R-}a\quad
    &&R_{\max}=R_0+\varepsilon_{R+}a\nonumber\\
    Z_{\min}&=-\varepsilon_{Z-}ae\quad
    &&Z_{\max}=\varepsilon_{Z+}ae
\end{align}
where $a$ is the minor radius, $e$ is the elongation of the flux surfaces and
the $\varepsilon$ are free parameters to be specified by the user.

The boundary conditions for the potential and the magnetic potential are not
penalized and thus hold on the bounding box. Typically we choose
\begin{align}
\phi = 0
\text{ and }  \hat n \cn A_{\parallel} = 0
\end{align}
where $\hat n$ is the normal vector to the boundary. The perpendicular boundary
conditions for the remaining fields become obsolete with the following
penalization scheme.

\begin{tcolorbox}[title=Note]
    Computing on a box and cutting away the parts that are the wall,
    for typical tokamak shapes incur a (loosely) estimated 50\% overhead in vector size:
    \begin{align*}
        \text{ number of points in box } = 1.5 \times \text{ number of points in area with plasma}
    \end{align*}
\end{tcolorbox}

\subsubsection{The wall region}
Being a box, our computational domain is in particular not aligned with the
magnetic flux surfaces. This means that particularly in the corners of
the domain the field lines inside the domain are very short (in the
sense that the distance between the entry point and leave point is short).
It turns out that this behaviour is numerically disadvantageous (may
blow up the simulation in the worst case) in the
computation of parallel derivatives.
In order to remedy this situation
we propose a penalization method to model the actual physical wall.
We define an approximation to the step function with a transition layer of radius $a$
around the origin
\begin{align}
\Theta_a(x) := \begin{cases}
    0 & \text{ for } x \leq -a  \\
    \frac{1}{32 a^7}  \left(16 a^3-29 a^2 x+20 a x^2-5 x^3\right) (a+x)^4
    &\text{ for } -a<x\leq a \\
    1 & \text{ for } x > a
\end{cases}
    \approx H(x)
\label{eq:approx_heaviside}
\end{align}
where $H(x)$ is the Heaviside step function.
%An integral of this function is
%\begin{align}
%\theta_a(x) := \begin{cases}
%    0 &\text{ for } x \leq -a \\
%    \frac{1}{256 a^7} \left(35 a^3-47 a^2 x+25 a x^2-5 x^3\right) (a+x)^5
%     &\text{ for } -a<x\leq a \\
%x &\text{ for } x > a
%\end{cases}
%    \approx x H(x)
%\end{align}
%Note that $\Theta_a(0) = 0.5$ and $\theta_a(0) = 35a/256$.
%
We now use the region defined by
\begin{align}\label{eq:wall}
    \chi_w(R,Z,\varphi):=\Theta_{\alpha/2}\left(\psi_{p,b} + \frac{\alpha}{2} - \psi \right) \approx H(\psi_{p,b}-\psi)
\end{align}
to define the wall region.
In order to simplify the setup of this region we give $\psi_{p,b}$ and $\alpha$ in terms of
$\rho_p$ and $\alpha_p$ via $\psi_{p,b} = (1-\rho_{p,b}^2)\psi_{p,O}$ and $\alpha = -(2\rho_{p,b} \alpha_p + \alpha_p^2)\psi_{p,O}$. In case we change the sign
of $\psi_p$ via $\mathcal P_\psi$ (to make it concave) note that $\alpha$ becomes
negative and $\psi_{p,O}$ is positive).
We then need to point mirror Eq.~\eqref{eq:wall} at $\psi_{p,b}+\frac{\alpha}{2}$.

Now, our idea is to dampen the density and velocity in the region defined by the
wall to 1 or 0 respectively.
For both electrons and ions we choose
\begin{subequations} \label{eq:wall_penalization}
\begin{align}
    S^w_N(R,Z,\varphi, t) &:= -\omega_w\chi_w (N-1)\\
    S^w_U(R,Z,\varphi, t) &:= -\omega_w\chi_w U_\parallel
\end{align}
\end{subequations}
where $\omega_w \gg 1$ is the penalization parameter.
\subsubsection{The sheath region}
In order to define sheath boundary conditions we first define a sheath region
and then determine whether the field lines point toward the wall or away from it.
We define as sheath any part on the bounding box that is not included in the wall
penalization. Then we check for each point in the box the poloidal distance to
the sheath wall and if the poloidal field points toward or away from the wall closest
to it.
We then take $\theta_{\alpha/2}\left( (\eps_s + \frac{\alpha}{2})a - d(R,Z)\right)$
and take the set intersection between that region and the ``not wall'' region to
determine the sheath penalization region:
\begin{align}\label{eq:sheath}
    \chi_s := \left(1-\chi_w(R,Z,\varphi)\right) \theta_{\alpha/2}\left( \left(\eps_s + \frac{\alpha}{2}\right)a - d(R,Z)\right)
\end{align}
Within the sheath region we penalize
\begin{subequations} \label{eq:sheath_penalization}
\begin{align}
    S^s_N(R,Z,\varphi, t) &:= \omega_s \chi_s \left(N_{sh}-N\right)\\
    S^s_{U_i}(R,Z,\varphi, t) &:= \omega_s \chi_s \left(\sqrt{1+\tau} - U_{\parallel,i} \right) \\
    S^s_{u_e}(R,Z,\varphi, t) &:= \omega_s \chi_s \left(\sqrt{1+\tau}\exp(-\phi) - u_{\parallel,e} \right) \text{ or }
    S^s_{u_e}(R,Z,\varphi, t) := \omega_s \chi_s \left(\sqrt{1+\tau} - u_{\parallel,e} \right)
\end{align}
\end{subequations}
where $\omega_s$ is the sheath penalization parameter and $N_{sh}$ is obtained by extrapolating $N$ along the magnetic field line with
the help of the parallel derivative operators
\begin{align}
    N_{sh} = \Tpm N \text{ such that } \nabla_\parallel N|_{sh} = 0
\end{align}
where the sign depends again on the direction of the magnetic field line (we always extrapolate ``downstream'').
The extrapolation models a parallel Neumann boundary condition for the density.
The boundary condition for the parallel electron velocity can be either the Bohm condition containing the contribution from the electric potential or
an insulating condition where the total current $j_s = n_e ( U_{\parallel,i} - u_{\parallel,e})$ vanishes.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Initial conditions}
We initialize the parallel velocity to zero
\begin{align}
  u_{\parallel,e}(R,Z,\varphi,0) = U_{\parallel,i}(R,Z,\varphi,0) = 0
  \label{}
\end{align}
which in turn initializes $A_\parallel = 0$
and initialize the electron density with
\begin{align} \label{eq:initial_ne}
    n_e(R,Z,\varphi, 0)= n_{prof}(R,Z) + \tilde n(R,Z,\varphi)
\end{align}
consisting of a toroidally symmetric background profile $n_{\text{prof}}(R,Z)$ and a perturbation
$\tilde n(R,Z,\varphi)$, which breaks the toroidal symmetry.
Note that we should take care to intitialize a smooth profile with ideally well-defined $\Delta^2_\perp n_e$.

We define a flux-aligned density profile as
\begin{align} \label{eq:density_profile}
  n_{\text{prof}}(R,Z)=
  n_0 + \triangle n_{peak}\frac{\psi_p(R,Z) }{\psi_{p,O}}\Theta_{\alpha_p/2}\left(1-\rho_p(R, Z)-\frac{\alpha_p}{2}\right) H(Z-Z_X)
\end{align}
The second Heaviside is multiplied only if the equilibrium $\psi_p$ has an
X-point and avoids a profile in the private flux region. The factor $\alpha_p$ provides a smooth transition
zone that avoids numerical oscillations.

We have two possibilities to initialize the ion density
\begin{align} \label{eq:initphi}
  N_i = \Gamma_{1,i}^{-1} n_e \text{ or } N_i = \Gamma_{1,i}n_e\approx \left(1+\frac{1}{2}\tau_i\mu_i\Delta_\perp\right)n_e
\end{align}
In the first case the potential $\phi= 0$ while in the second case
the $E\times B$ and ion diamagnetic vorticity coincide $\Delta_\perp N_i \propto \Delta_\perp \phi$ in the long-wavelength limit.
Note that $\alpha$ must not be too small to avoid $N_i < 0$.
We can choose between several initial conditions for $\tilde n$:

\subsubsection{Blob and Straight blob}
We initialize a blob in the R-Z plane
\begin{align} \label{eq:initial_blob}
  \tilde n_{blob}(R,Z,0) = \triangle n \exp\left( -\frac{(R - R_0 - p_x a)^2 + (Z-p_ya)^2}{\sigma^2} \right)
\end{align}
Then, we use fieldline integration modulated by
\begin{align}
  m_{blob}(s) = \exp\left( -\frac{s^2 }{\pi^2\sigma_z^2} \right)
\end{align}
to transform this blob to all other poloidal
planes.
We either follow fieldlines around the torus several times (``blob'') or only once
(``straight blob'').
\subsubsection{Turbulent bath}
We can initialize the R-Z plane with a turbulent bath with a certain amplitude $A$.
This especially has the goal to destabilize the edge region right inside the
last closed flux surface. Notice that the core region is rather stable
and quickly damps away fluctuations.
Again, we transform this to all poloidal planes along the magnetic field lines and multiply the bath with
\begin{align} \label{eq:initial_turbulent}
    \tilde n_e(R,Z,\varphi) = \tilde n_{\text{bath}}(R,Z,\varphi)\Theta_{\alpha_p/2}(-\rho_p(R, Z)-\alpha_p/2) H(Z-Z_X)
\end{align}
\subsubsection{Zonal flows}
We can initialize the R-Z plane with zonal flows of amplitude $A$ and
wavelength $k_\psi$ aligned with the magnetic flux surfaces.
\begin{align} \label{eq:initial_zonal_flow}
    \tilde n_{\text{zonal}}(R,Z) &= A \sin (2\pi k_\psi \psi_p(R,Z)) \nonumber\\
\tilde n_e(R,Z,\varphi) &= \tilde n_{\text{zonal}}(R,Z)\Theta_{\alpha_p}\left(-\rho_p(R, Z)-\frac{\alpha_p}{2}\right) H(Z-Z_X)
\end{align}
\subsubsection{Turbulence on Gaussian profile}
Instead of the flux-aligned profile we can also choose a toroidally symmetric Gaussian profile
\begin{align} \label{eq:profile_blob}
  n_{prof}(R,Z) = n_0 + \triangle n_{peak} \exp\left( -\frac{(R - R_0 - p_x a)^2 + (Z-p_ya)^2}{\sigma^2} \right)
\end{align}
on top of which we can add the turbulent bath $\tilde n_{\text{bath}}$ and finally dampen it by
\begin{align}\label{eq:turbulence_on_gaussian}
    n_e(R,Z,\varphi,0) = (n_{prof}(R,Z) + \tilde n_{\text{bath}})\Theta_{\alpha_p/2}\left( 1- \sqrt{(R-R_0)^2 + Z^2}/a\right)
\end{align}

\subsection{Sinks and sources} \label{sec:sources}
We can choose the source terms $S_N$ to either force a profile
$n_{\text{prof}}$ or provide a constant influx of particles in the
core of our domain, where our model does not apply.
We thus define a particle sink/source for electrons as
\begin{align} \label{eq:electron_source}
  S_{n_e}(R,Z,\varphi, t) &= \omega_s \begin{cases}
      (n_{prof}(R,Z) - n_e(R,Z,\varphi, t))\Theta_{\alpha_p/2}\left( \rho_{p,s} - \frac{\alpha_p}{2} - \rho_p(R,Z) \right ) H(Z-Z_X) \quad \text{ forced}\\
    S_{prof}(R,Z)\quad \text{ influx}
    \end{cases}
\end{align}
where $\omega_s$ is the source strength parameter. The shift of $\Theta$ is chosen
such that the source vanishes exactly outside $\psi_{p,s}$.
The forced source will result in exponential adaption of the core
density profile of the form $n_e \propto n_{prof}+(n_{prof}-n_{e,0})e^{-\omega_st}$.

We can choose the constant influx
\begin{align} \label{eq:electron_source_influx}
    S_{prof}(R,Z) &= \Theta_{\alpha_p/2}\left( \rho_{p,s} - \frac{\alpha_p}{2} - \rho_p(R,Z) \right) H(Z-Z_X)
\end{align}
or a ringed Gaussian TCV source of the form
\begin{align}
    S_{prof}(R,Z) &= \exp\left( -\frac{(\psi_p-\psi_{p,0})^2}{\sigma^2}\right)H(Z-Z_X)
\end{align}
with $\psi_{p,0} = \psi_p(1075, -10)$ and $\sigma = 0.0093\psi_{p,0}/0.4$,
or a Torpex inspired source profile
\begin{align} \label{eq:electron_source_torpex}
  S_{prof}(R,Z) &=
  \begin{cases}
    \exp\left( - \frac{(R-R_0)^2}{a^2 }- \frac{(Z-Z_0)^2}{b^2}\right) \text{ if} R > R_0 \\
    \frac{1}{2}\exp\left( - \frac{(R-R_0)^2}{a^2} -2c(R-R_0)(Z-Z_0)- \frac{(Z-Z_0)^2}{b^2} \right) \\
  +\frac{1}{2}\exp\left( - \frac{(R-R_0)^2}{a^2} +2c(R-R_0)(Z-Z_0)- \frac{(Z-Z_0)^2}{b^2} \right) \text{ else}
              \end{cases}
\end{align}
with $a=0.0335$m, $b=0.05$m, $c=565m^{-2}$, $R_0=0.98$m and $Z_0=-0.02$m.

In order to not generate potential with the source term the
ion source needs to fulfill $S_{n_e} = \Gamma_{1,i}S_{N_i} + \nc\left( \frac{\mu_i S_{N_i}}{B^2}\np \phi\right)$ which in the long wavelength limit can be inverted to (the long wavelength limit should be well-fulfilled for a realistic source term since the amplitude is typically quite small)
\begin{align}
    S_{N_i} = \left(1-\frac{1}{2}\mu_i \tau_i \Delta_\perp\right) S_{n_e} -\nc\left( \frac{\mu_i S_{n_e}}{B^2}\np \phi\right)
  \label{eq:ion_source}
\end{align}
Note that the additional terms besides $S_{n_e}$ are total divergences which means
they do not change the volume integrated "total" particle number created by the source.
Note that $S_{n_e}$ needs to be smooth
so that $\np^2 S_{n_e}$ is well defined.
Also note that with our definition of $\Lambda_{n_e}$ and $\Lambda_{N_i}$ and
the polarisation equation we have $\Lambda_{n_e} = \Gamma_{1,i}\Lambda_{N_i} + \nc\left( \frac{\mu_i \Lambda_{N_i}}{B^2}\np \phi\right)$ in the long wavelength limit (swap the operators).
This means that diffusion does not generate potential either.

\subsection{Implemented form}
We use a conservative form of the continuity equation
in the perpendicular terms and else avoids derivatives on the product of two
functions for which we have no boundary condition.
\begin{subequations}
    \begin{align}
    \frac{\partial}{\partial t} N =&
    \left[ - \frac{1}{\sqrt{g}} \partial_i \left( \sqrt{g} N \left( \frac{\epsilon^{ijk} b_j \partial_k \psi}{\sqrt{g}B}
    + \tau K^i
    + \mu U_\parallel^2 K_{\vn\times\bhat}^i
    + U_\parallel\left( A_\parallel K_{\vn\times\bhat}^i +\frac{\epsilon^{ijk} \partial_j A_\parallel b_k}{\sqrt{g}B}   \right)
    \right)\right)\right. \nonumber\\
    &\left.- \npar \left( NU_\parallel\right)
        - NU_\parallel\vec \nc\bhat
        %\frac{1}{B}[\psi, N]_{\perp} %\nonumber\\
        %- \tau \mathcal K(N)\right. \nonumber \\&
        %\left.
        %- N \mathcal K(\psi)
        %-\mu \mathcal K_{\vn\times\bhat}(NU_\parallel^2)
        %-\mu NU_\parallel^2\nc \vec{ K_{\vn\times\bhat}}
    - \nu_\perp\Delta_\perp^2 N + S_N\right]
    (1-\chi_s - \chi_w) \nonumber\\& + \omega_s\chi_s( N_{sh} - N) + \omega_w \chi_w (1-N), \\
    \frac{\partial}{\partial t} W_\parallel =&
  \left[- \frac{1}{B}\left[\psi, U_\parallel\right]_{\perp}%& \nonumber\\
        - \frac{1}{\mu} \bar \npar \psi% \nonumber\\
        - \frac{1}{2}\bar \npar U_\parallel^2
        -\frac{\tau}{\mu} \bar \npar \ln N
        - U_\parallel\mathcal K_{\vn\times\bhat}(\psi)
        - \tau \mathcal K(U_\parallel)
        -\tau U_\parallel\nc\vec{ K_{\vn\times\bhat}}
    \right.
        \nonumber\\&
    \left.- \left(2\tau + {\mu}U_\parallel^2\right) \mathcal K_{\vn\times\bhat} (U_\parallel)
        -2\tau U_\parallel\mathcal K_{\vn\times\bhat}(\ln N)
        - \frac{\eta}{\mu} \frac{n_e}{N}n_e(U_{\parallel,i} - u_{\parallel,e})
    \right.\nonumber\\&
    \left.+ \frac{\nu_\parallel}{N} \Delta_\parallel U_\parallel - \nu_\perp\Delta_\perp^2 U_\parallel
    + S_U\right]
    (1-\chi_s - \chi_w) + \omega_s\chi_s ( U_{\parallel}^{sh} - U_\parallel) -\omega_w \chi_wU_\parallel
    ,
        \label{eq:EgyrofluidU} \\
        W_\parallel&:= \left( U_\parallel + \frac{A_\parallel}{\mu}\right)
    \end{align}
    \label{eq:Egyrofluid}
\end{subequations}
together with
$\bar\npar f = \npar f + A_\parallel \mathcal K_{\vn\times\bhat}(f) + \frac{1}{B}[ f, A_\parallel]_\perp$
%and $\nc { \vec b}_\perp = A_\parallel \vec \nc\vec{ { K}_{\vn\times\bhat}} - \mathcal K_{\vn B}(A_\parallel) $
and
\begin{subequations} \label{eq:elliptic}
  \begin{align}
    -\nc\left( \frac{N_i}{B^2}\np \phi \right) &= \Gamma_{1,i} N_i - n_e, \quad\quad
    \Gamma_{1,i}^{-1} = 1-\frac{1}{2}\tau_i\mu_i \Delta_\perp \\
    \psi_e = \phi, \quad \psi_i &= \Gamma_{1,i}\phi -\frac{\mu_i}{2}\frac{(\np\phi)^2}{B^2} \\
    \left(\frac{\beta}{\mu_i}N_i - \frac{\beta}{\mu_e}n_e-\Delta_\perp\right)
    A_\parallel &= \beta\left(N_iW_{\parallel,i}-n_e w_{\parallel,e}\right)
  \end{align}
\end{subequations}
\begin{tcolorbox}[title=Note]
The negative signs make the operators in Eqs.~\eqref{eq:elliptic} positive definite.
\end{tcolorbox}

In the output file we have
\begin{longtable}{llll}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Equation} & \textbf{Name} &  \textbf{Equation}\\
\midrule
    electrons &$n_e$ &
    ions &$N_i$ \\
    Ue &$u_{\parallel,e}$ &
    Ui &$U_{\parallel,i}$ \\
    potential &$\phi$ &
    psi &$\psi$ \\
    induction &$A_\parallel$ & \\
\bottomrule
\end{longtable}
\subsection{ Scale invariance}
\subsubsection{Sign reversals of the magnetic field}\label{sec:field_reversal}
If we change the direction of the magnetic field vector $\bhat$, we immediately see that all perpendicular
drifts and $U_\parallel\bhat$ change directions. On the other side, the diffusive and resistive terms remain unchanged.
Without resistivity and diffusion a change in direction of the magnetic field thus corresponds to
a time reversal $t\rightarrow t'=-t$.
In the code $\bhat$ changes sign by using both $-\mathcal P_\psi$ and $-\mathcal P_I$.

Also note that changing the sign of the magnetic field only in the parallel derivatives $\npar \rightarrow -\npar$ does not
have any effect. This can be seen by simply renormalizing $U_\parallel'=-U_\parallel$. This reverts the equations back to the original equations.
\subsubsection{Scaling of density}
If $N, U_\parallel, \phi, A_\parallel$ are a solution to the model equations
then so are $N'=\alpha N$, $U_\parallel'=U_\parallel$, $\phi'=\phi$ and $A_\parallel'=A_\parallel$ with the changed parameters $S_N' = \alpha S_N$, $\eta' = \eta/\alpha$ and $ \beta' = \beta/\alpha$. If $N$
has a Dirichlet boundary condition, then $N'$ satisfies a correspondingly scaled boundary condition.
\subsubsection{Helicity}
The standard helicity of the magnetic field would be a right handed screw,
where the magnetic field and the toroidal plasma current point in the clockwise
direction if the tokamak is seen from above.
The helicity should however not have any influence on the plasma dynamics. With
a mirror transformation (view the tokamak in a mirror) we should be able
to transform the solution to one with reversed helicity.

\subsection{Conservation laws} \label{sec:conservation}
\subsubsection{Mass conservation}
The density equations directly yield the particle conservation
\begin{align} \label{eq:mass_theorem}
  \frac{\partial}{\partial t} N
  + \nc\vec{ j_{N}}
  =  \Lambda_{N}+S_{N}
\end{align}
The terms of the particle conservation thus read
\begin{align}
  N= & N,\\
  \vec j_{N} =& N\left(
  \vec u_\psi + \vec u_C + \vec u_{K} +U_\parallel\left(\bhat+{\vec b}_\perp\right)  \right)
\label{eq:particle_flux}\\
  %\nonumber\\
  %=& N \left(\frac{\bhat\times \vn\phi}{B}
  %+ \tau_e \frac{\bhat\times\vn n_e}{n_eB}
  %+ \mu_e u_{\parallel,e}^2\vec K_{\vn\times\bhat}
  %+ u_{\parallel,e}(\bhat + {\vec b}_\perp) \right), \\
  \Lambda_{N} =&
  \nu_\perp\Delta_\perp N% + \nu_\parallel\Delta_\parallel N
\\
  S_{N} =&  S_{N}
\end{align}
Notice that
\begin{align}
\tau N \vec K = \tau N\vn\times\frac{\bhat}{B} = \tau \vn\times N\frac{\bhat}{B} + \tau \frac{\bhat\times\vn N}{B}
\label{}
\end{align}
such that we can define the diamagnetic flux in the particle flux since
the rotation vanishes under the divergence.

We here also derive the particle flux \eqref{eq:particle_flux} through a flux surface
\begin{align} \label{eq:radial_particle_flux}
 \vec j_{N}\cn v %=& N\left( \vec u_E + \vec u_C + \vec u_{\vn
 %B} + U_\parallel \left(\bhat + {\vec b}_\perp\right)\right) \cn \psi_p \nonumber\\
 =&
  \frac{\d v}{\d \psi_p} N\left[\frac{1}{B}[\psi, \psi_p]_\perp + \left(\tau + \mu U_\parallel^2\right)
   \mathcal K_{\vn\times\bhat}(\psi_p) + \tau  \mathcal K_{\vn B}(\psi_p) \right] \nonumber\\
 &+ NU_\parallel\frac{\d v}{\d \psi_p}\left [\left( A_\parallel \mathcal
 K_{\vn\times\bhat}(\psi_p) + \frac{1}{B}[\psi_p, A_\parallel]_\perp\right) \right]
\end{align}

The relevant terms in the output file are
\begin{longtable}{llll}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Equation} & \textbf{Name} &  \textbf{Equation}\\
\midrule
    electrons & $n_e$ &
    jsneC\_tt &$ n_e ( \vec u_K + \vec u_C )\cn \psi_p$ \\
    jsneA\_tt &$ n_e u_{\parallel,e} \vec{ b}_\perp  \cn \psi_p$ &
    jsneE\_tt & $ n_e \vec u_E\cn\psi_p$ \\
    lneperp\_tt &$ \Lambda_{\perp,n_e} = \nu_\perp \Delta_\perp n_e$ or $-\nu_\perp \Delta^2_\perp n_e$ &
    & \\
    %lneparallel\_tt &$ \Lambda_{\parallel,n_e} = \nu_\parallel \Delta_\parallel n_e$ \\
    sne\_tt & $S_{n_e}$ &
    jsdiae\_tt & $\tau_e \bhat \times \vn n_e \cn \psi_p /B$\\
    dnepar\_tt & $\nc (\bhat n_e u_{e,\parallel}$) &
    & \\
    ions & $N_i$ &
    jsniC\_tt &$ N_i ( \vec u_K + \vec u_C )\cn \psi_p$ \\
    jsniA\_tt &$ N_i U_{\parallel,i} \vec{ b}_\perp  \cn \psi_p$ &
    jsniE\_tt & $ N_i \vec u^i_E\cn\psi_p$ \\
    lniperp\_tt &$ \Lambda_{\perp,N_i} = \nu_\perp \Delta_\perp N_i$ or $-\nu_\perp \Delta^2_\perp N_i$ &
    & \\
    %lniparallel\_tt &$ \Lambda_{\parallel,N_i} = \nu_\parallel \Delta_\parallel N_i$ \\
    sni\_tt & $S_{N_i}$ &
    jsdiai\_tt & $\tau_i \bhat \times \vn N_i \cn \psi_p /B$\\
    dnipar\_tt & $\nc (\bhat N_i U_{i,\parallel}$) &
      & \\
\bottomrule
\end{longtable}

Note that the parallel divergences vanish exactly under a flux-surface average. This can serve as a numerical test of our implementation.
\subsubsection{Energy theorem}
The terms of the energy theorem are
\begin{align} \label{eq:energy_theorem}
\partial_t \mathcal E +
\nc \vec j_{\mathcal E}
= \Lambda_{\mathcal E}
+  S_{\mathcal E}
+  R_{\mathcal E}
\end{align}
with ( $z_e=-1$ and $z_i=+1$) and $\vec u_E := {\bhat\times \vn\phi}/{B}$
\begin{align} \label{eq:energy_conservation}
  \mathcal{E}= & z_e\tau_e n_e \ln{(n_e)} +z_i\tau_i N_i\ln{(N_i)}
  +\frac{1}{2\beta}\left(\np A_\parallel\right)^2
   +  \frac{1}{2} z_i \mu_i N_i u_E^2  \nonumber\\
   & +\frac{1}{2} z_e\mu_e  n_e u_{\parallel,e}^2
  +\frac{1}{2} z_i\mu_i  N_i U_{\parallel,i}^2,\\
  \vec j_{\mathcal E} =& \sum_s z\left[
  \left(\tau \ln N + \frac{1}{2}\mu U_\parallel^2 + \psi \right)N\left(
  \vec u_E + \vec u_C + \vec u_{K} +U_\parallel\left(\bhat+{\vec b}_\perp\right)  \right) \right]
  \nonumber\\
  &+ \sum_z z\left[\mu \tau NU_\parallel^2\vec K_{\vn\times\bhat} + \tau NU_\parallel \left(\bhat + {\vec b}_\perp\right)\right], \\
  \Lambda_{\mathcal E} =&  \sum_s z\left[\left( \tau\left( 1+\ln{N}\right) + \psi + \frac{1}{2} \mu U_\parallel^2 \right)
  \left(\nu_\perp\Delta_\perp N \right)  +  \mu NU_\parallel\left(\nu_\perp\Delta_\perp U_\parallel + \nu_\parallel\Delta_\parallel U_\parallel\right) \right]
\nonumber \\
  S_{\mathcal E} =&  \sum_s  z\left[ \left(\tau\left( 1+\ln{N}\right) +\psi + \frac{1}{2} \mu U_\parallel^2 \right)S_{N}\right]
\nonumber \\
  R_{\mathcal E} =&  -\eta_\parallel  \left[ n_e(U_{\parallel,i}-u_{\parallel,e})\right]^2.
\end{align}
where in the energy flux $\vec j_{\mathcal E}$
we neglect terms  containing time derivatives
of the eletric and magnetic potentials and we sum over all species.
The energy density $\mathcal E$ consists of the Helmholtz free energy density for electrons and ions,
the \(\vec{E} \times \vec{B}\) energy density, the parallel energy densities for electrons and ions and the perturbed magnetic field energy density.
In \(\Lambda\) we insert the dissipative terms of Section~\ref{sec:dissres}. \\
Replace $\Delta_\perp$ with $-\Delta_\perp^2$ when hyperviscous diffusion is chosen
for the diffusion terms in the above equations.

We have the energy flux through a flux surface
\begin{align}
 \vec j_{\mathcal E}\cn v =&%\frac{\d v}{\d \psi_p} \vec j_{\mathcal E}\cn \psi_p  =
\frac{\d v}{\d \psi_p}\sum_s z\left (\tau\ln N + \frac{1}{2}\mu U_\parallel^2 + \psi\right) \vec j_N\cn\psi_p
+ z \mu\tau NU_\parallel^2 \mathcal K_{\vn\times\bhat}(\psi_p) \nonumber\\
&+ z \tau NU_\parallel
 \left( A_\parallel \mathcal
 K_{\vn\times\bhat}(\psi_p) + \frac{1}{B}[\psi_p, A_\parallel]_\perp\right)
\label{eq:energy_flux}
\end{align}
The relevant terms in the output file are
\begin{longtable}{ll}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Equation}\\
\midrule
    nelnne &$ z_e\tau_e n_e \ln n_e$ \\
    nilnni &$ z_i\tau_i N_i \ln N_i$ \\
    aperp2 &$ (\np A_\parallel)^2/2/\beta$ \\
    ue2   &$z_i\mu_i N_i u_E^2 /2$ \\
    neue2 &$ z_e\mu_e n_e u_{\parallel,e}^2/2$ \\
    niui2 &$ z_i\mu_i N_i U_{\parallel,i}^2/2$ \\
    see\_tt & $z_e(\tau_e (1+\ln n_e) + \phi + \frac{1}{2}\mu_e u_{\parallel,e}^2) S_{n_e} $ \\
    sei\_tt & $z_i(\tau_i (1+\ln N_i) + \psi + \frac{1}{2}\mu_i U_{\parallel,i}^2) S_{N_i} $ \\
    resistivity\_tt &-$\eta_\parallel n_e^2 (U_{\parallel,i}-u_{\parallel,e})^2$ \\
    jsee\_tt &$z_e(\tau_e \ln n_e + \mu_e u_{\parallel,e}^2/2 + \phi)n_e(\vec u_E + \vec u_C + \vec u_K)\cn \psi_p
        + z_e \tau_e n_e u_{\parallel,e}^2 \vec K_{\vn\times\bhat}\cn \psi_p$ \\
    jsei\_tt &$z_i(\tau_i \ln N_i + \mu_i U_{\parallel,i}^2/2 + \psi_i)N_i(\vec u_E^i + \vec u_C + \vec u_K)\cn \psi_p
        + z_i \tau_i N_i U_{\parallel,i}^2 \vec K_{\vn\times\bhat}\cn \psi_p$ \\
    jseea\_tt &$z_e(\tau_e \ln n_e + \mu_e u_{\parallel,e}^2 + \phi)n_e \vec { b}_\perp\cn \psi_p
        + z_e \tau_e n_e u_{\parallel,e} \vec{ b}_\perp \cn \psi_p $ \\
    jseia\_tt &$z_i(\tau_i \ln N_i + \mu_i U_{\parallel,i}^2 + \psi_i)N_i \vec { b}_\perp\cn \psi_p
        + z_i \tau_i N_i U_{\parallel,i} \vec{ b}_\perp \cn \psi_p $ \\
    leeperp\_tt &$z_e(\tau_e(1+\ln n_e) + \phi + \mu_eu_{\parallel,e}^2/2) \nu_\perp \Delta_\perp n_e + z_e\mu_e n_e u_{\parallel,e} \nu_\perp \Delta_\perp u_{\parallel,e}$ \\
    leiperp\_tt &$z_i(\tau_i(1+\ln N_i) + \psi_i + \mu_iU_{\parallel,i}^2/2) \nu_\perp \Delta_\perp N_i + z_i\mu_i N_i U_{\parallel,i} \nu_\perp \Delta_\perp U_{\parallel,i}$ \\
    leeparallel\_tt & %$z_e(\tau_e(1+\ln n_e) + \phi + \mu_eu_{\parallel,e}^2/2) \nu_\parallel \Delta_\parallel n_e +$
    $z_e\mu_e n_e u_{\parallel,e} \nu_{\parallel,e} \Delta_\parallel u_{\parallel,e}$ \\
    leiparallel\_tt & %$z_i(\tau_i(1+\ln N_i) + \psi_i + \mu_iU_{\parallel,i}^2/2) \nu_\parallel \Delta_\parallel N_i + $
    $z_i\mu_i N_i
    U_{\parallel,i} \nu_{\parallel,i} \Delta_\parallel U_{\parallel,i}$ \\
\bottomrule
\end{longtable}

\subsubsection{Toroidal ExB angular momentum equation} \label{sec:vorticity_eq}
We integrate the polarisation equation over volume, multiply by $\d \psi_p/\d v$ and derive by time. In the drift-ordering up to order $\mathcal O(\delta^3)$ we get
\begin{align}
    &\partial_t \RA{\Omega} + \frac{\partial}{\partial v}\frac{\d v}{\d\psi_p}\RA{\vec j_\Omega\cn\psi_p} = -\RA{F_{L,\varphi}} + \RA{\mathcal S_\Omega} \label{eq:vorticity_average} \\
\Omega &:= \mu_i N_i \left(\frac{\vn\psi_p\cn\phi}{B^2} + \tau_i \vn\ln N_i\cn\psi_p\right) \equiv \mu_i N_i(u_{E,\varphi} + u_{D,\varphi}) \\
\vec j_{\Omega} &:= \Omega \vec u_E
    - \left(\frac{1}{\beta} \vn\psi_p \cn A_\parallel +\frac{1}{2}\tau_i \vn\psi_p\cn  (N_iU_{\parallel,i})\right)\frac{\bhat\times\vn A_\parallel}{B} \\
    F_{L,\varphi} &:=  -(z_e \tau_e n_e + z_i\tau_i N_i)\mathcal K(\psi_p) - (z_e\mu_e n_eu_{\parallel,e}^2 + z_i\mu_i N_iU_{\parallel,i}^2)\mathcal K_{\vn\times\bhat}(\psi_p) \\
    \mathcal S_\Omega &:= \mu_i S_{n_e} \frac{\vn\psi_p\cn \phi}{B^2} + \mu_i\tau_i\vn\psi_p\cn S_{n_e} \label{eq:em_source}
\end{align}
Equation~\eqref{eq:vorticity_average} can be rewritten by inserting the continuity equation to yield an equation only for the \ExB angular momentum. Again up to order $\mathcal O(\delta^3)$ in the drift ordering we obtain
(the diffusive term is for testing purposes)
\begin{align}
&\partial_t \RA{\Omega_E} + \frac{\partial}{\partial v} \frac{\d v}{\d \psi_p}\RA{ \vec j_{\Omega_E}\cn\psi_p} = -\RA{F_{L,\varphi}}+ \RA{\mathcal S_{\Omega_E}} + \RA{\Lambda_{\Omega_E}} \label{eq:exb_average} \\
\Omega_E &:= \mu_i N_i \frac{\vn\psi_p\cn\phi}{B^2} \equiv \mu_i N_i u_{E,\varphi} \\
\vec j_{\Omega_E} &:= \Omega_E (\vec u_E + \vec u_D)
    - \vn A_\parallel\cn\psi_p \left(\frac{1}{\beta} \frac{\bhat\times\vn A_\parallel}{B} +\frac{1}{2} \bhat \times \vn \mu_i \tau_i N_iU_{\parallel,i}\right) \\
    \mathcal S_{\Omega_E} &:= \mu_i S_{n_e} \frac{\vn\psi_p\cn\phi}{B^2} \quad
    \Lambda_{\Omega_E} := \mu_i \Lambda_{n_e}\frac{\vn\psi_p\cn\phi}{B^2}
\end{align}
where here we also monitor the source and diffusion terms.
In the output file we have
\begin{longtable}{llll}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Equation}&
\textbf{Name} &  \textbf{Equation}\\
\midrule
    oexbe &$\mu_i n_e \frac{\vn\psi_p\cn\phi}{B^2}$ &
    oexbi &$\mu_i N_i \frac{\vn\psi_p\cn\phi}{B^2}$ \\
    odiae &$\mu_i \tau_i\vn\psi_p\cn n_e$ &
    odiai &$\mu_i \tau_i\vn\psi_p\cn N_i$ \\
    jsoexbi\_tt &$\mu_i N_i \frac{\vn\psi_p\cn\phi}{B^2} \frac{\bhat\times\vn\phi\cn \psi_p}{B}$ &
    jsoexbe\_tt &$\mu_i n_e \frac{\vn\psi_p\cn\phi}{B^2} \frac{\bhat\times\vn\phi\cn \psi_p}{B}$ \\
    jsodiaiUE\_tt &$\mu_i \tau_i\vn\psi_p\cn N_i \frac{\bhat\times\vn\phi\cn \psi_p}{B}$ &
    jsodiaeUE\_tt &$\mu_i \tau_i\vn\psi_p\cn n_e \frac{\bhat\times\vn\phi\cn \psi_p}{B}$ \\
    jsoexbiUD\_tt &$\mu_i\tau_i \frac{\vn\psi_p\cn\phi}{B^2} \frac{\bhat\times\vn N_i\cn \psi_p}{B}$ &
    jsoexbeUD\_tt &$\mu_i\tau_i \frac{\vn\psi_p\cn\phi}{B^2} \frac{\bhat\times\vn n_e\cn \psi_p}{B}$ \\
    jsoapar\_tt &$ -\vn\psi_p\cn A_\parallel \frac{\bhat\times\vn A_\parallel\cn \psi_p}{B\beta}$ &
    jsodiaApar\_tt & $ -\frac{1}{2}\tau_i \vn\psi_p\cn  (N_iU_{\parallel,i})\frac{\bhat\times\vn A_\parallel}{B}\cn\psi_p$ \\
    jsoexbApar\_tt & $ -\frac{1}{2}\tau_i \bhat\times\vn  (N_iU_{\parallel,i})\cn\psi_p \vn A_\parallel\cn\psi_p$ &
    socurve\_tt &$z_e\tau_e n_e \mathcal K(\psi_p)$ \\
    socurvi\_tt &$z_i\tau_i N_i \mathcal K(\psi_p)$ &
    socurvkappae\_tt &$z_e\mu_e n_eu_{\parallel,e}^2 \mathcal K_{\vn\times\bhat}(\psi_p)$ \\
    socurvkappai\_tt &$z_i\mu_i N_iU_{\parallel,i}^2 \mathcal K_{\vn\times\bhat}(\psi_p)$ & \\
    sosne\_tt & $\mu_i S_{n_e} \vn\psi_p\cn\phi/B^2$ &
    sospi\_tt & $\mu_i \tau_i \vn\psi_p \cn S_{n_e}$\\
    loexbe\_tt & $ \mu_i \Lambda_{n_e} \vn\psi_p\cn\phi/B^2$ & \\
\bottomrule
\end{longtable}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Parallel momentum balance}
The flux surface average over the parallel momentum equation under species summation  yields up to order $\mathcal O(\delta^3)$ in the drift-ordering
\begin{align}
  \frac{\partial}{\partial t}\RA{\mu_iN_iU_{\parallel,i} }
    % \nonumber\\
    + \frac{\partial}{\partial v} \frac{\d v}{\d\psi_p} \RA{\mu_iN_iU_{\parallel,i} \frac{\bhat\times\vn\phi}{B}\cn\psi_p + \sum_s (z_s\tau_sN_s + z_s\mu_s N_sU_{\parallel,s}^2) b_{\perp}^{\;v}  }
    \nonumber\\
   = \sum_s\RA{-z_s\tau_s N_s\npar \ln B} + \mu_i \RA{ S_{N_i} U_{\parallel,i} + N_i S_{U_\parallel}}
   \label{eq:parallel_momentum}
\end{align}
while the toroidal parallel angular momentum contribution reads up to order $\mathcal O(\delta^3)$
\begin{align}\label{eq:parallel_momentum_direction}
    \frac{\partial}{\partial t}  \RA{\mu_iN_iU_{\parallel,i} b_\varphi}
    + \frac{\partial}{\partial v} \frac{\d v}{\d\psi_p} \RA{\mu_iN_iU_{\parallel,i} b_\varphi\frac{\bhat\times\vn\phi}{B}\cn\psi_p + \sum_s (z_s\tau_s N_s + z_s\mu_sN_sU_{\parallel,s}^2) b_\varphi b_{\perp}^{\;v} }
    \nonumber\\
    = \RA{F_{L,\varphi}} + \mu_i \RA{ (S_{N_i} U_{\parallel,i} + N_i S_{U_\parallel}) b_\varphi}
\end{align}

The relevant terms in the output file are (the Lorentz force term is described in the previous subsection \ref{sec:vorticity_eq})
\begin{longtable}{llll}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Equation} &
\textbf{Name} &  \textbf{Equation}\\
\midrule
    neue &$n_e u_{\parallel,e}$ &
    niui &$\mu_i N_i U_{\parallel,i}$ \\
    neuebphi &$n_eu_{\parallel,e}b_\varphi$ &
    niuibphi &$\mu_i N_iU_{\parallel,i}b_\varphi$ \\
    jsparexbi\_tt       & $\mu_i N_iU_{\parallel,i}(\bhat\times\vn\phi)\cn \psi_p/B$ &
    jsparbphiexbi\_tt   & $\mu_i N_iU_{\parallel,i}b_\varphi(\bhat\times\vn\phi)\cn \psi_p/B$ \\
    jspardiai\_tt       & $\mu_i \tau_i N_iU_{\parallel,i}\vec K\cn\psi_p$ &
    jsparbphdiai\_tt   & $\mu_i \tau_i N_iU_{\parallel,i}b_\varphi\vec K\cn\psi_p$ \\
    jsparkappai\_tt       & $\mu_i N_iU_{\parallel,i} ( \mu_i U_{\parallel,i}^2 + 2\tau_i)\vec K_{\vn\times \bhat}\cn\psi_p$ &
    jsparbphikappai\_tt       & $\mu_i N_iU_{\parallel,i}b_\varphi ( \mu_i U_{\parallel,i}^2 + 2\tau_i)\vec K_{\vn\times \bhat}\cn\psi_p$ \\
    jsparApar\_tt       & $\sum_s (z_s \tau_s N_s + z_s \mu_s N_s U_{\parallel,s}^2)b_\perp^v$ &
    jsparbphiApar\_tt   & $\sum_s (z_s \tau_s N_s + z_s \mu_s N_s U_{\parallel,s}^2)b_\varphi b_\perp^v$ \\
    sparmirrore\_tt & $-z_e\tau_en_e\npar \ln B$ &
    sparmirrori\_tt & $-z_i\tau_iN_i\npar \ln B$ \\
    sparsni\_tt & $\mu_i S_{N_i} U_{\parallel,i} + \mu_i S_{U_i} N_i $ &
    sparsnibphi\_tt & $\mu_i S_{N_i} U_{\parallel,i}b_\varphi + \mu_i S_{U,i} N_i b_\varphi $ \\
    lparpar\_tt   & $\nu_{\parallel,i} \Delta_\parallel U_{\parallel,i}$ &
    lparperp\_tt & $-\nu_\perp U_{\parallel,i} \Delta_\perp^2 N_i - \nu_\perp N_i\Delta_\perp^2 U_{\parallel,i} $ \\
\bottomrule
\end{longtable}
Note that the parallel viscosity term vanishes exactly under the flux-surface average. This can serve as a numerical test.

\subsubsection{Parallel electron force balance}
We gather the dominant terms in the electron momentum equation (neglecting all terms as $\mu_e=0$). This leaves the parallel force balance
\begin{align}
    -(\bhat + \vec b_\perp) \cn n_e +n_e\left( \left( \bhat + \vec b_\perp \right) \cn \phi + \frac{\partial A_\parallel}{\partial t} \right) +\eta n_e^2 \left( U_{\parallel,i} - u_{\parallel,e}\right) = 0
\end{align}
\begin{longtable}{llll}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Equation} &
\textbf{Name} &  \textbf{Equation}\\
\midrule
    sparphie\_tt & $n_e\npar \phi$ &
    friction\_tt & $ \eta n_e^2(U_{\parallel,i}-u_{\parallel,e})$ \\
    sparmirrore\_tt & $-\npar n_e$ &
    sparmirrorAe\_tt & $-\vn A_\parallel \times \bhat \cn n_e /B$ \\
    sparphiAe\_tt & $n_e \vn A_\parallel \times \bhat \cn \phi /B$ &
    spardotAe\_tt & $ n_e \partial A_\parallel /\partial t$ \\
\bottomrule
\end{longtable}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsubsection{Zonal flow energy}
\begin{align}
    E_\mathrm{zonal} = \frac{1}{2}\RA{\rho_M}\FA{ \iota^{-2}\mathcal I^{\vartheta\vartheta} + 2\iota^{-1}\mathcal I^{\vartheta\varphi} + \mathcal I^{\varphi\varphi}} \FA{u_{E,\varphi}}^2
    \equiv \frac{1}{2} \RA{\rho_M} \FA{u_{E,\varphi}}^2  \FA{\mathcal I_0}
    \label{eq:zonal_energy}
\end{align}
For symmetry flux coordinates we have $g_{\vartheta\vartheta} = R^2 (\vn\psi_p)^2/I^2\iota^2$, $g_{\varphi\vartheta} =0$ and $g_{\varphi\varphi}=R^2$ and thus $\mathcal I_0 = R^{-2}( 1 + I^2/|\vn\psi_p|^2)= B^2 / |\vn\psi_p|^2$.
\begin{align}\label{eq:perp_kinetic}
      \frac{\partial}{\partial t}E_{\mathrm{zonal}} +\frac{\partial}{\partial v } \left(E_{\mathrm{zonal}}\FA{u^v} \right)
  =&-\FA{\mathcal I_0}\FA{u_{E,\varphi}}\left(\frac{\partial }{\partial v}  \Theta_{\varphi}^{\; v} + \RA{(\vec j_f\times\vec B)_\varphi}\right)
  \nonumber\\
    &-\frac{1}{2}\FA{u_{E,\varphi}}^2\frac{\partial}{\partial v}\left(\RA{\rho_M}\FA{\FF{\mathcal I_0}\FF{u^v}}\right)
     + \mathcal S_{\mathrm{zonal}}
\end{align}
where we neglected the term $\RA{n\vec u\cn \mathcal I_0}$ in the continuity equation as small in our ordering
 and we have
 \begin{align}
 \mathcal S_{\mathrm{zonal}} :=& \FA{\mathcal I_0} \FA{u_{E,\varphi}} \mathcal S_{u_{E,\varphi}} + \frac{1}{2}\FA{u_{E,\varphi}}^2  \RA{mS_n\mathcal I_0}
%  \nonumber\\
 \label{eq:zonal_source}
 \end{align}
 and in the output file
\begin{longtable}{llll}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Equation} &
\textbf{Name} &  \textbf{Equation}\\
\midrule
    nei0 &$n_e \mathcal I_0$ &
    snei0\_tt & $S_{n_e } \mathcal I_0$ \\
\bottomrule
\end{longtable}

\subsection{Manufactured Solution}
In order to test the implementation we manufacture a solution to Eqs.~\eqref{eq:Egyrofluid} and \eqref{eq:elliptic} of the form
\begin{align*}
n_e(R,Z,\varphi, t) &:= 1 + 0.5\sin(\pi(R-R_0))\sin(\pi Z)\sin(\varphi)\sin(\pi t) \\
N_i(R,Z,\varphi, t) &:= n_e(R,Z,\varphi,t) = \gamma_{ N_i}  \\
u_{\parallel,e}(R,Z,\varphi, t) &:= \sin(2\pi(R-R_0))\sin(2\pi Z)\sin(2\varphi)\sin(2\pi t)/(3\sqrt{-\mu_e}) \\
U_{\parallel,i}(R,Z,\varphi, t) &:= \sqrt{-\mu_e}u_{\parallel,e}(R,Z,\varphi,t) \\
\phi(R,Z,\varphi,t) &:= \sin(3\pi(R-R_0))\sin(3\pi Z)\sin(3\varphi)\sin(3\pi t)/5; \\
\psi(R,Z,\varphi,t) &:= \phi(R,Z,\varphi, t) = \gamma_{\phi} \\
A_\parallel( R,Z,\varphi,t) &:= \beta\sin(4\pi(R-R_0))\sin(4\pi Z)\sin(4\varphi)\sin(4\pi t)/4;
\end{align*}
We choose circular flux surfaces of the form
\begin{align*}
\psi_p(R,Z) :=0.5((R-R_0)^2 + Z^2),\quad
I_p(R,Z):=I_0
\end{align*}
with $R_0=10$ and $I_0=20$ and a simulation box $[R_0-a,R_0+a]\times[-a,a]\times[0,2\pi]$.
We then symbolically compute (with the help of Mathematica) source terms that we insert to the right hand side of
the corresponding equation in code (\texttt{manufactured.h}) and simulate from $t=0...10^{-3}$.
By comparing the numerical solution to the manufactured one we can observe the convergence of our numerical methods. Note that in order to better distinguish
the convergence of the DG discretized terms from our parallel derivative
we can selectively choose to only activate perpendicular (including $A_\parallel$ terms) or parallel terms (those that involve derivatives along $\bhat$).

Unfortunately, we were unable to find a closed solution for the energy integrals with the above fields.

\section{Numerical methods}
discontinuous Galerkin on structured grid
\rowcolors{2}{gray!25}{white} %%% Use this line in front of longtable
\begin{longtable}{p{3cm}p{3cm}p{8cm}}
\toprule
\rowcolor{gray!50}\textbf{Term} &  \textbf{Method} & \textbf{Description}  \\ \midrule
    coordinate system & Cylindrical & equidistant discretization of $[R_{\min},R_{\max}] \times [Z_{\min},Z_{\max}] \times [0,2\pi]$ (Eq.~\eqref{eq:box}, equal number of Gaussian nodes in $R$ and $Z$, equidistant planes in $\varphi$ with one Gaussian node \\
Advection terms & direct DG & DG approximation with centered flux of derivatives \\
Elliptic terms & local DG & The local DG approximation with centered flux \\
Helmholtz and Elliptic matrix inversions & multigrid/ conjugate gradient & Use previous two solutions to extrapolate initial guess and $1/\chi$ as preconditioner \\
Parallel derivatives & regular  FCI & cf.~\cite{Held2016,Stegmeir2017}.
All terms use the direct centered difference, which turns out is best
at keeping the numerical flux-surface leakage in $\RA{\nc ( \bhat NU_\parallel)}$ to a minimum, even
though it is not exactly zero like in the adjoint discretizations, which in turn are unusable because they do not reliably converge.
There seems to be no benefit in using the grid refinement technique except when field-aligning the initial condition.
%The terms $\npar N$ and $\npar \phi$ in the velocity equation use a forward difference, while the term $\npar U_\parallel$ in the
%density equation uses backward difference. This is to avoid a too wide stencil for the diverence of the current and increases stability for low resistivity.
\\
time & Multistep "Karniadakis" & \\
\qquad explicit & Multistep "Karniadakis" & $3$rd order explicit\\
\qquad implicit & Multistep "Karniadakis" & $2$nd order implicit, contains the penalization term and optionally the perp. Diffusion terms. \\
\bottomrule
\end{longtable}
Note that the explicit resistive term leads to an absolute (CFL) restriction
on the timestep according to $\partial_t u_e \propto \frac{\eta}{\mu_e} u_e \Rightarrow \Delta t < \frac{-\mu_e}{\eta}$. This is a quite weak restriction unless the resistivity exceeds $\eta > 10^{-4}$.
The explicit parallel electron viscosity term leads to a CFL condition of the
form $\Delta t < (2\pi (R_0 - a))^2/(N_z^2 \nu_{\parallel,e})$.

In every iteration of the implicit inversion we need to solve an equation of the form
\begin{align}
    n_e + a \hat L n_e = \hat n_e \\
    N_i + a \hat L N_i = \hat N_i \\
    w_e + a \hat L u_e = \hat w_e \\
    W_i + a \hat L U_i = \hat W_i
\end{align}
with $W=U+A_\parallel/\mu$ and $-\Delta_\perp A_\parallel = \beta (N_i U_i -n_e u_e)$
    and $\hat L = -\nu_\perp \Delta_\perp^2$.
This makes 7 equations for 7 unkown quantities.
We solve the system by first isolating and solving the two density equations for $n_e$ and $N_i$. These can then be inserted into the velocity equations as
fixed solutions, which makes these equations linear.

The resistive term cannot fit into this scheme as it is linear but not symmetric.
\section{Usage}

Compilation:\\
\texttt{make feltor device=\{gpu,omp\}} Compile \texttt{feltor.cu} (only shared memory)\\
\texttt{make feltor\_hpc device=\{gpu,omp\}} Compile \texttt{feltor\_hpc.cu} for shared memory system. Needs {\it serial netcdf} \\
\texttt{make feltor\_mpi device=\{gpu,omp,skl,knl\}} Compile \texttt{feltor\_hpc.cu} for distributed memory systems. Also needs {\it serial netcdf}\\
Usage:\\
\texttt{./feltor\_hpc input.json geometry.json output.nc [initial.nc]} \\
\texttt{echo npx npy npz | mpirun -n np ./feltor\_mpi input.json geometry.json output.nc [initial.nc]} \\
\texttt{./feltor input.json geometry.json } \\

The programs \texttt{feltor\_hpc.cu} and \texttt{feltor.cu} expect two input
files \texttt{input.json} and \texttt{geometry.json}, described in Sections~\ref{sec:input_file} and \ref{sec:geometry_file}.
The first is for the physical and numerical parameters of the model equations
while the latter describes the Solov'ev equilibrium.
 The program \texttt{feltor.cu} plots the results directly to the screen using \texttt{glfw3}.
The program \texttt{feltor\_hpc.cu} writes results into
the output file \texttt{output.nc}.
 The output file is described in Section~\ref{sec:output_file}.
 The optional file \texttt{initial.nc} can be used to initialize a simulation from an existing file.
 This behavior is described in Section~\ref{sec:restart_file}.
 Both programs write unstructured human readable performance information of the running simulation
 to \texttt{std::cout}.

\begin{tcolorbox}[title=Note]
When compiled for mpi, the program \texttt{feltor\_hpc.cu} expects the
partition of the total number of processes np into the three directions x, y and z
as an input from the command line.
\end{tcolorbox}
Make sure that \texttt{npx*npy*npz==np} and that
they evenly divide the number of grid points in the respective direction! The
number of stages in the multigrid algorithm and the compression parameters further
restrict this choice. Also note that the number of processes in a direction must
not equal the number of grid points in that direction!

\subsection{Input file structure} \label{sec:input_file}
Input file format: \href{https://en.wikipedia.org/wiki/JSON}{json}

%%This is a booktabs table
\begin{longtable}{llp{2.5cm}p{7cm}}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Type} & \textbf{Example}  & \textbf{Description}  \\ \midrule
n      & integer & 3 &Number of Gaussian nodes in R and Z (we practically always take 3)
\\
Nx     & integer &52&Number of grid points in R (increase if your simulations crash)
\\
Ny     & integer &52&Number of grid points in Z (increase if your simulations crash)
\\
Nz     & integer &16&Number of grid points in $\varphi$ (determines dt
since parallel velocity dominates timestep)
\\
dt     & integer &1e-2& time stepsize in units of $c_s/\rho_s$ \\
compression & integer[2] & [2,2] & Compress output file by reducing
points in x and y (pojecting the polynomials onto a coarser grid): output
contains n*Nx/c[0] points in x, (has to divde Nx evenly), and n*Ny/c[1] points
in y, (has to divde Ny evenly). 2 or 3 are reasonable values.
\\
inner\_loop & integer & 2  & Number of time steps between updates to the
time integrated quantities. (Although the diagnostics is quite fast sometimes
you need to amortize the time spent on it). Note that integrating selected
quantities in time during the simulation is how we maintain the time-resolution
in the file output (cf. \ref{sec:output_file}). Choose as low as you can get
away with (between 1 and 10).
\\
itstp       & integer & 2  &{ \tt inner\_loop*itstp} is the number of
timesteps between file outputs (2d and 3d quantities); Note that 1d and 0d
quantities can only be computed post-simulation since we can't compute
flux-integrals in parallel in MPI.
\\
maxout      & integer & 10 & Total Number of fields outputs excluding first
(The total number of time steps is {\tt maxout$\cdot$itstp$\cdot$inner\_loop})
If you want to let the simulation run for a certain time instead just choose
this parameter very large and let the simulation hit the time-limit.
\\
eps\_time   & float & 1e-7  & Tolerance for solver for implicit part in
time-stepper (if too low, you'll see oscillations in $u_{\parallel,e}$ and/or $\phi$) Relevant only if diffusion is treated implicitly.
\\
stages      & integer & 3 & number of stages in multigrid, $2^{\text{stages-1}}$
has to evenly divide both $N_x$ and $N_y$
\\
eps\_pol    & float[stages] & [1e-6,1,1]  &  The first number is the tolerance for residual of the inversion of polarisation and induction Eq.. The second number is a multiplicative factor for the accuracy on the second grid in a multigrid scheme, the third for the third grid and so on.  (i.e. $\eps_0\eps_i$ is the accuracy on the i-th grid)
Tuning those factors is a major performance tuning oppourtunity!! For saturated turbulence the suggested values are [1e-6, 2000, 100].
\\
jumpfactor  & float & 1 & Jumpfactor $\in \left[0.01,1\right]$ in the local DG method for the elliptic terms. (Don't touch unless you know what you're doing.
\\
eps\_gamma  & float & 1e-6  & Tolerance for $\Gamma_1$
\\
FCI & dict & & Parameters for Flux coordinate independent approach
\\
\qquad refine     & integer[2] & [2,2] & refinement factor in FCI approach in R- and Z-direction.
We use [2,2], higher values take more time, but possibly stabilize the simulation.
\\
\qquad rk4eps     & float & 1e-6 & Accuracy of fieldline integrator in FCI. The default is reasonable.
\\
\qquad periodify & bool & true & Indicate if flux function is periodified beyond grid boundaries such that the contours are perpendicular to the boundaries. This is not entirely consistent but works better for small toroidal resolution
\\
mu         & float & -0.000272121& $\mu_e =-m_e/m_i$.
    One of $\left\{ -0.000544617, -0.000272121, -0.000181372 \right\}$
\\
tau        & float &1      & $\tau = T_i/T_e$
\\
beta       & float & 5e-6  & Plasma beta $5\cdot 10^{-6}$ (TJK), $4\cdot
10^{-3}$ (Compass), If $0$, then the model is electrostatic
\\
nu\_perp   & float &1e-3   & perpendicular viscosity $\nu_\perp$, increase
this or the resolution if you see vertical or horizontal oscillations (likely
from the advection terms) in your simulation box, decrease if it dampens all
instabilities
\\
perp\_diff & string[2] & ["viscous","explicit"] & "viscous": $\Lambda_\perp\propto
\nu_\perp\Delta_\perp$ , "hyperviscous": $\Lambda_\perp \propto
-\nu_\perp\Delta_\perp^2$, the second entry indicates whether the perpendicular diffusion is to be treated explicit or implicit (we recommend explicit since in 3d the parallel dynamics restricts the timestep)
\\
resistivity & float &1e-4  & parallel resistivity parameter Eq.~\eqref{eq:resistivity}
\\
curvmode  & string & "toroidal" &
curvature mode (
"low beta",
"true": no approximation - requires significantly more resolution in Nz,
"toroidal": toroidal field approx - elliptic equation does not need
communication in z
)
\\
symmetric & bool & false & If true, initialize all quantities symmetric
in $\varphi$ (effectively reducing the problem to 2d). The input $N_z$ is used
to construct the parallel derivatives and then overwritten to $N_z\equiv 1$.
\\
bc & dict & & Perpendicular Boundary conditions (note that $A_\parallel$ has the same bc as $U_\parallel$) \ldots\\
\qquad density   & char[2] & [DIR,DIR] & boundary conditions in x and y
for $n_e$ and $N_i$, DIR (density 1 on boundary) means both convective and
    diffusive outflow while NEU (gradient 0) means no outflow by diffusion
\\
\qquad velocity  & char[2] & [NEU,NEU] & boundary conditions in x and y for
$u_{\parallel,e}$ and $U_{\parallel,i}$ and $A_\parallel$, DIR is in general not very stable, NEU works
better\\
\qquad potential & char[2] & [DIR,DIR] & boundary conditions in x and y for
$\phi$ and $\psi$, DIR means that the $v_{E,\perp}=0$ on the boundary (i.e. no
outflow by \ExB drift), NEU can have a detrimental effect on timestep \\
box & dict & & Bounding box \\
    \qquad scaleR  & float[2] & [1.1,1.1]     & $[\varepsilon_{R-}, \varepsilon_{R+}]$ scale left and right boundary in units of $a$ Eq.~\eqref{eq:box}\\
    \qquad scaleZ  & float[2] & [1.2,1.1]     & $\varepsilon_{Z-}, \varepsilon_{Z+}$ scale lower and upper boundary in units of $ae$ Eq.~\eqref{eq:box}
\\
initne    & string & "turbulence"     & initial condition for the
perturbation $\tilde n$ in \eqref{eq:initial_ne}. "zonal" (Eq.~\eqref{eq:initial_zonal_flow}),
    "zero" = no perturbation,
    "blob" = blob simulations (several rounds fieldaligned),
    "straight blob" = straight blob simulation( 1 round fieldaligned),
    "turbulence" = turbulence simulations ( 1 round fieldaligned, Eq.~\eqref{eq:initial_turbulent})
    "turbulence on gaussian" = Gaussian bg. profile with turbulence perturbation Eq.~\eqref{eq:turbulence_on_gaussian}
    See the file {\tt init.h} to add your own custom condition.
\\
initphi   & string & "zero"  & (ignored if $\tau_i = 0$, then $\phi=0$) initial condition for $\phi$ and thus $N_i$ (Eq.~\eqref{eq:initphi}: "zero" : $\phi = 0$, vanishing
electric potential, "balance": ExB vorticity equals ion diamagnetic vorticity
\\
amplitude  & float &0.01   & amplitude $A$ of initial perturbation (blob, turbulent bath or zonal flow)  \\
sigma      & float &2      & Gaussian variance in units of $\rho_s$ \\
posX       & float &0.3    & Gaussian R-position in units of $a$\\
posY       & float &0.0    & Gaussian Z-position in units of $a$ \\
sigma\_z    & float &0.25  & toroidal variance in units of $\pi$ of the fieldline-following initialization \\
k\_psi     & float &0    & zonal mode wave number (only for "zonal" initial condition)  \\
profile & Dict & & Density profile \\
\qquad amp& float &4   & Profile amplitude $\triangle n_{peak}$ in
Eq.~\eqref{eq:density_profile} and Eq.~\eqref{eq:turbulence_on_gaussian}
\\
\qquad alpha  & float & 0.2 & Transition width $\alpha_p$ in the Heaviside
at the separatrix (must not be zero - even if amp is zero - it is also used for the perturbation)
\\
source & dict & & Density source, cf. the output \texttt{sne\_tt\_ifs} in \texttt{feltordiag} (or \texttt{SourceProfile\_ifs} in \texttt{geometry\_diag}) to see how much mass the source with the parameters below generates and compare to \texttt{jsne\_tt\_fsa} to see how much mass is lost.  \\
\qquad rate & float & 0    & profile source rate $\omega_s$ in Eq.~\eqref{eq:electron_source}.
\\
\qquad type & string & "influx" & The type of source to use:
"fixed\_profile" the source is multiplied by $(n_{prof} - n)$ to relax to the initial profile Eq.~\eqref{eq:electron_source};
"influx" the source has a constant source rate Eq.~\eqref{eq:electron_source_influx},
"torpex": Torpex inspired source profile Eq.~\eqref{eq:electron_source_torpex},
"gaussian": Gaussian shaped source profile - uses \texttt{posX}, \texttt{posY} and \texttt{sigma},
"profile\_influx": Copy a profile into the source function and use a constant source rate. The idea is that you can start with zero density and evolve the profile purely with the source. There is a turbulent bath on top of it.
"turbulence" : Influx of the turbulent bath initial condition as a source, same as profile\_influx just without the profile.
    See the file {\tt init.h} to add your own custom source.
\\
\qquad boundary & float & 0.2  & Source region boundary $\rho_{p,b}$: yields in Eq.~\eqref{eq:electron_source} and Eq.~\eqref{eq:electron_source_influx}  \\
\qquad alpha  & float & 0.2 & Transition width $\alpha_p$ in the Heaviside
in the density Eq.~\eqref{eq:density_profile} (with $\rho_{p,b}=0$ and source profiles Eq.~\eqref{eq:electron_source} (should be
small but cannot be too small if $\tau_i > 0$ else $\Delta_\perp n_e$ explodes, must not be zero)
\\
wall & dict & & magnetic and density damping region \\
\qquad type & string & "sol\_pfr" & One of ``none'', ``heaviside'' or ``sol\_pfr'' \\
\qquad penalization & float & 1    & penalization coefficient $\omega_w$ in density and velocity damping Eq.~\eqref{eq:wall_penalization} \\
\qquad boundary & float[2] & [1.2,0.8]  & Wall region boundary $\rho_{p,b}$: yields $\psi_0 = (1-\rho_{p,b}^2)\psi_{p,O}$ in Eq.~\eqref{eq:wall}.
\\
\qquad alpha   & float[2] & [0.25,0.25] & Transition width $\alpha_p$: yields
$\alpha=-2\rho_{p,b}\alpha_p+\alpha_p^2)\psi_{p,O}$ for the Heaviside in the wall function \eqref{eq:wall}. If zero, we do not have a wall.
\\
sheath & dict & & Sheath region and boundary condition \\
\qquad bc & string & "bohm" & One of ``bohm'',  or ``insulation'' \\
\qquad penalization & float & 1    & penalization coefficient $\omega_s$ in density and velocity damping Eq.~\eqref{eq:sheath_penalization} \\
\qquad boundary & float & 0.3  & Wall region boundary $\rho_{p,b}$: yields $\psi_0 = (1-\rho_{p,b}^2)\psi_{p,O}$ in Eq.~\eqref{eq:sheath}.
\\
\qquad alpha   & float & 0.2 & Transition width $\alpha_p$: yields
$\alpha=-2\rho_{p,b}\alpha_p+\alpha_p^2)\psi_{p,O}$ for the Heaviside in the wall function \eqref{eq:sheath}.
\\
\bottomrule
\end{longtable}
\subsection{Geometry file structure} \label{sec:geometry_file}
File format: \href{https://en.wikipedia.org/wiki/JSON}{json}

The file structure of the geometry file depends on which expansion for $\psi_p$ is chosen Eq.~\eqref{eq:solovev} or Eq.~\eqref{eq:polynomial}.
%%This is a booktabs table
A solovev magnetic field equilibrium
\begin{longtable}{lll>{\RaggedRight}p{7cm}}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Type} & \textbf{Example} & \textbf{Description}  \\ \midrule
    A      & float & 0 & Solovev parameter in Eq.~\eqref{eq:solovev} \\
    c      & float[12] &  - & Solovev coefficients in Eq.~\eqref{eq:solovev} \\
\bottomrule
\end{longtable}
A polynomial magnetic field equilibrium
\begin{longtable}{lll>{\RaggedRight}p{7cm}}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Type} & \textbf{Example} & \textbf{Description}  \\ \midrule
    M      & float & 1 & Number of polynomial coefficients in $R$ in Eq.~\eqref{eq:polynomial} \\
    N      & float & 1 & Number of polynomial coefficients in $Z$ in Eq.~\eqref{eq:polynomial} \\
    c      & float[MN] &  - & Polynomial coefficients in Eq.~\eqref{eq:polynomial} \\
\bottomrule
\end{longtable}
In addition both files must contain
\begin{longtable}{lll>{\RaggedRight}p{7cm}}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Type} & \textbf{Example} & \textbf{Description}  \\ \midrule
    PP     & float & 1 & Prefactor $\mathcal P_\psi$ for $\psi_p$ \\
    PI     & float & 1 & Prefactor $\mathcal P_I$ for $I$ \\
    R\_0   & float & - & Major radius $R_0$ in units of $\rho_s$ (This is the only geometry quantity to change if $\rho_s$ changes)\\
    elongation    & float & 1 & Elongation $e$, used in determining the box size Eq.~\eqref{eq:box} and the initial guess for the location of the X-point $Z_X = -1.1 ea$ \\
    triangularity & float & 0 & Triangularity $\delta$, used in the initial guess for the location of the X-point $R_X = R_0-1.1\delta a$ \\
    inverseaspectratio & float & 0.16667& minor to major radius $a/R_0$ (used to compute $a$ from $R_0$) \\
    equilibrium & string & solovev & Tells the magnetic field generation which type of expansion to use for the flux function \\
    description & string & standardX & Tells the magnetic field modifier
    where to look for the SOL and PFR regions \\
\bottomrule
\end{longtable}

\subsection{Output} \label{sec:output_file}
Output file format: \href{https://www.unidata.ucar.edu/software/netcdf/docs/}{netcdf-4/hdf5};

A \textit{coordinate variable (Coord. Var.)} is a Dataset with the same name as a dimension.
We follow
\href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html}{CF Conventions CF-1.7}
and write according attributes into the file.

\begin{tcolorbox}[title=Note]
The command \texttt{ncdump -h output.nc} gives a full list of what a file contains.
\end{tcolorbox}
Here, we list the content without attributes
since the internal netcdf information does not display equations.
%
%Name | Type | Dimensionality | Description
%---|---|---|---|
\begin{longtable}{lll>{\RaggedRight}p{7cm}}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Type} & \textbf{Dimension} & \textbf{Description}  \\ \midrule
inputfile  &     text attribute & - & verbose input file as a string (valid JSON, C-style comments are allowed but discarded) \\
geomfile   &     text attribute & - & verbose geometry input file as a string (valid JSON, C-style comments are allowed but discarded) \\
x                & Coord. Var. & 1 (x) & $R$-coordinate (computational space, compressed size: $nN_x/c_x$)\\
y                & Coord. Var. & 1 (y) & $Z$-coordinate (computational space, compressed size: $nN_y/c_y$)\\
z                & Coord. Var. & 1 (z) & $\varphi$-coordinate (computational space, size: $N_z$) \\
time             & Coord. Var. & 1 (time)& time at which fields are written (variable size: maxout$+1$, dimension size: unlimited) \\
xc           & Dataset & 3 (z,y,x) & Cartesian x-coordinate $x=R\sin(\varphi)$ \\
yc           & Dataset & 3 (z,y,x) & Cartesian y-coordinate $y=R\cos(\varphi)$\\
zc           & Dataset & 3 (z,y,x) & Cartesian z-coordinate $z=Z$ \\
Psip             & Dataset & 3 (z,y,x) & Flux function $\psi_p(R,Z)$ \\
Nprof            & Dataset & 3 (z,y,x) & Density profile $n_\text{prof}$ used in the forcing source \\
Source           & Dataset & 3 (z,y,x) & Source profile $S_{prof}$\\
BR               & Dataset & 3 (z,y,x) & Contravariant magnetic field component $B^R$ \\
BZ               & Dataset & 3 (z,y,x) & Contravariant magnetic field component $B^Z$ \\
BP               & Dataset & 3 (z,y,x) & Contravariant magnetic field component $B^\varphi$ \\
electrons        & Dataset & 4 (time, z, y, x) & electron density $n_e$ \\
ions             & Dataset & 4 (time, z, y, x) & ion density $N_i$ \\
Ue               & Dataset & 4 (time, z, y, x) & electron velocity $u_{\parallel,e}$ \\
Ui               & Dataset & 4 (time, z, y, x) & ion velocity $U_{\parallel,i}$ \\
potential        & Dataset & 4 (time, z, y, x) & electric potential $\phi$ \\
induction        & Dataset & 4 (time, z, y, x) & parallel vector potential $A_\parallel$ \\
X\_2d            & Dataset & 3 (time,y,x) & Selected plane $X(\varphi=0)$ \\
X\_ta2d          & Dataset & 3 (time,y,x) & Toroidal average $\PA{ X }$
Eq.~\eqref{eq:phi_average} \\
Y\_tt\_2d        & Dataset & 3 (time,y,x) & Time integrated (between two outputs, Simpson's rule) selected plane
$\int_{t_0}^{t_1}\d t Y(\varphi=0) $
where $t_1 - t_0 = ${\tt dt*inner\_loop*itstp} and {\tt itstp} is the number of discretization points\\
Y\_tt\_ta2d      & Dataset & 3 (time,y,x) & Time integrated (between two outputs, Simpson's rule) toroidal average (Eq.~\eqref{eq:phi_average})
$\int_{t_0}^{t_1}\d t \PA{ Y }$
where $t_1 - t_0 = ${\tt dt*inner\_loop*itstp} and {\tt itstp} is the number of discretization points\\
\bottomrule
\end{longtable}
where
X and Y\_tt represent the quantities described in the tables in previous sections and the miscellaneous quantities
\begin{longtable}{llll}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Equation} & \textbf{Name} &  \textbf{Equation}\\
\midrule
    vorticity &$-\Delta_\perp\phi$ &
    apar\_vorticity &$-\Delta_\perp A_\parallel$ \\
    dssue & $\npar^2 u_{\parallel,e}$&
    %dppue & $\partial_\varphi^2 u_{\parallel,e}$\\
    %dpue2 & $(\partial_\varphi u_{\parallel,e})^2$&
    lperpinv &$L_\perp^{-1} := |\vec\np n_e|/n_e$ \\
    perpaligned &$(\vec\np n_e)^2/n_e$ &
    lparallelinv &$L_\parallel^{-1} := |\npar n_e|/n_e$ \\
    aligned &$ (\npar n_e)^2/n_e$ &
    ne2 & $n_e^2$ \\
    phi2 & $\phi^2$ &
    nephi & $n_e\phi$ \\
\bottomrule
\end{longtable}
The computation time spent on diagnostics is negligible if {\tt inner\_loop} parameter is greater than 1. Also
remember that the X and Y fields are all two-dimensional, which takes up much less disk-space than three-dimensional fields.
\subsection{Restart file} \label{sec:restart_file}
The program \texttt{feltor\_hpc.cu} has the possibility to initialize time and the fields with
the results of a previous simulation. In particular, this feature is motivated by chain jobs on a cluster
(see e.g. the --dependency option in SLURM).
This behaviour is enabled by giving an additional file \texttt{initial.nc}
to the command line. In this case the \texttt{initne} and \texttt{initphi} parameters of the input
file are ignored. Instead, the fields \texttt{electrons, ions, Ue, Ui, induction} at the latest timestep
are read from the given file to initialize the simulation.
Note that to enable a loss-less continuation of the simulation we output special restart fields into the output file that in contrast to the other fields
are not compressed.
Apart from that the behaviour of the program is unchanged i.e. the magnetic field, profiles, resolutions, etc.
are all taken from the regular input files. This means that the user must take care that these are consistent
with the paramters in the existing \texttt{initial.nc} file. Also note that we try to discourage
appending new results to an exisiting file directly,
because if for some reason the cluster crashes and the file is corrupted
the whole simulation is lost.
\begin{tcolorbox}[title=Note]
It is safer to just merge files afterwards with\\
\texttt{ncrcat output1.nc output2.nc output.nc}\\
from the \texttt{nco} package
\end{tcolorbox}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Diagnostics}\label{sec:diagnostics}
\texttt{feltor/src/feltor/feltordiag.cu}
 reads one or more previously generated simulation file(s) \texttt{input0.nc ... inputN.nc} described in Section~\ref{sec:output_file} and writes into a single second output file \texttt{output.nc} described as follows. \\
Compilation\\
\texttt{make feltordiag device=\{gpu,omp\}} \\
Usage \\
\texttt{./feltordiag input0.nc ... inputN.nc output.nc} \\

\begin{tcolorbox}[title=Note]
\texttt{feltordiag} refuses to overwrite existing files in order to protect against data loss in case of accidental spelling
errors or other careless mistakes.
\end{tcolorbox}

Output file format: \href{https://www.unidata.ucar.edu/software/netcdf/docs/}{netcdf-4/hdf5};
\href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html}{CF Conventions CF-1.7}

A \textit{coordinate variable (Coord. Var.)} is a Dataset with the same name as a dimension.

\begin{longtable}{lll>{\RaggedRight}p{7cm}}
\toprule
\rowcolor{gray!50}\textbf{Name} &  \textbf{Type} & \textbf{Dimension} & \textbf{Description}  \\ \midrule
inputfile  &     text attribute & - & verbose input file as a string (valid JSON, C-style comments are allowed but discarded) \\
geomfile   &     text attribute & - & verbose geometry input file as a string (valid JSON, C-style comments are allowed but discarded) \\
x                & Coord. Var. & 1 (x) & $R$-coordinate (computational space, compressed size: $nN_x/c_x$)\\
y                & Coord. Var. & 1 (y) & $Z$-coordinate (computational space, compressed size: $nN_y/c_y$)\\
psi              & Coord. Var. & 1 (psi) & $\psi_p$-coordinate ( default size: $3\cdot 64$) \\
time             & Coord. Var. & 1 (time)& time at which fields are written (variable size: maxout$+1$, dimension size: unlimited) \\
dvdpsip          & Dataset & 1 (psi) & $\d v/\d\psi_p$ \\
psi\_vol         & Dataset & 1 (psi) & The volume enclosed by the flux surfaces $v(\psi_p) = \int_{\psi_p} \dV $ \\
psi\_area        & Dataset & 1 (psi) & The area of the flux surfaces $A(\psi_p) = 2\pi \int_\Omega |\vn\psi_p| \delta(\psi_p - \psi_{p0}) H(Z-Z_X) R\d R\d Z$ \\
q-profile        & Dataset & 1 (psi) & The safety factor $q(\psi_p)$ \eqref{eq:safety_factor} using direct integration ( accurate but unavailable outside separatrix) \\
psi\_psi         & Dataset & 1 (psi) & explicit $\psi_p$ values; Same as psi \\
psit1d           & Dataset & 1 (psi) & Toroidal flux (integrated q-profile) $\psi_t = \int^{\psi_p} \d\psi_p q(\psi_p)$ \\
rho              & Dataset & 1 (psi) & Transformed flux label $\rho:= 1 - \psi_p/\psi_{p,O}$ \\
rho\_p           & Dataset & 1 (psi) & poloidal flux label $\rho_p:= \sqrt{1 - \psi_p/\psi_{p,O}}$ \\
rho\_t           & Dataset & 1 (psi) & Toroidal flux label $\rho_t := \sqrt{\psi_t/\psi_{t,\mathrm{sep}}}$ (is similar to $\rho$ in the edge but $\rho_t$ is nicer in the core domain, because equidistant $\rho_t$ make more equidistant flux-surfaces)\\
Z\_fluc2d        & Dataset & 3 (time,y,x) & Fluctuation level on selected plane ($\varphi= 0$) $\delta Z := Z(R,Z,0) - \RA{ Z}(R,Z)$ \\
Z\_fsa2d         & Dataset & 3 (time, y,x) & Flux surface average $\RA{ Z}$ interpolated onto 2d plane Eq.~\eqref{eq:fsa_vol} \\
Z\_cta2d         & Dataset & 3 (time, y,x) & Convoluted toroidal average Eq.~\eqref{eq:cta} \\
Z\_fsa           & Dataset & 2 (time, psi) & Flux surface average $\RA{ Z}$ Eq.~\eqref{eq:fsa_vol} \\
Z\_std\_fsa      & Dataset & 2 (time, psi) & Standard deviation of flux surface average on outboard midplane $\sqrt{\RA{(\delta Z)^2}}$ \\
Z\_ifs           & Dataset & 2 (time, psi) & Volume integrated flux surface average $\int\d v\RA{ Z}$ unless Z is a current, then it is the volume derived flux-surface average $\partial_v \RA{ Z}$ \\
Z\_ifs\_lcfs     & Dataset & 1 (time) & Volume integrated flux surface average evaluated on last closed flux surface $\int_0^{v(0)}\d v\RA{ Z}$ unless Z is a current, then it is the fsa evaluated $\RA{ j_v}(0)$ \\
Z\_ifs\_norm     & Dataset & 1 (time) & Volume integrated square flux surface average $\sqrt{\int \d v \RA{Z}^2}$, unless Z is a current, then it is the square derivative of the flux surface average $\sqrt{\int\d v (\partial_v \RA{j^v})^2}$\\
\bottomrule
\end{longtable}
where Z $\in$ \{X, Y\_tt\}
\begin{tcolorbox}[title=Note]
\texttt{feltoridag} converts all $jsX$ quantities into $jvX$
by multiplying $\d v/\d \psi_p$
in the sense that $\vec j\cn v  = \vec j \cn \psi_p \d v/\d\psi_p$.
\end{tcolorbox}
The parameters used for the X-point flux-aligned grid construction are $f_x = 1/8$, $f_y = 0$, $n_\psi = 3$, $N_\zeta = 64$ and $N_\eta = 640$ and the constant monitor metric.

We also have a useful geometry diagnostic program:
\texttt{feltor/inc/geometries/geometry\_diag.cu} reads either a previously
generated simulation file \texttt{input.nc} or the input json files
\texttt{input.json} and \texttt{geometry.json} and writes an output file \texttt{diag\_geometry.nc} as\\
Compilation\\
\texttt{make geometry\_diag device=\{gpu,omp\}} \\
Usage \\
\texttt{./geometry\_diag input.json geometry.json diag\_geometry.nc} \\
The program outputs a host of static 1d, 2d and 3d geometric quantities.
The output file is for example useful in connection with the ``Group Datasets'' filter in paraview, which merges Datasets from different files into one using shallow copy only.
\section{Troubleshooting}
All previously mentioned codes can crash for various reasons. Here,
we list and describe situations, which generally may lead to program
termination
\begin{longtable}{p{6cm}p{8cm}}
\toprule
\rowcolor{gray!50}\textbf{Error condition} &  \textbf{Handling} \\ \midrule
An input file does not exist or is otherwise invalid
&
Program terminates with an error message to \texttt{std::cerr}. \texttt{feltordiag.cu} writes an error to \texttt{std::cerr} and continues with the next input file.
    \\
An input netcdf file misses a required field
&
Program terminates with a NetCDF error message to \texttt{std::cerr}
    \\
No write permission for the output file location
&
Program terminates with an error message to \texttt{std::cerr}
    \\
An input Json file misses a key or contains a typo in a key
&
The programs \texttt{feltor.cu} and \texttt{feltor\_hpc.cu}
will exit with an error message. (The reason why we do not
silently use the default value is that the danger of wasting
valuable computing time on the cluster due to a typo is bigger than the
added convenience. We want to be sure that the program
does what the user wants).
The other programs just issue warnings
if a key is not found and use a default value
which is $0$ if not otherwise specified.
    \\
    An input Json file has an invalid value, e.g. a typo in a string value
&
Invalid values lead to termination with an error message to \texttt{std::cerr}, once and if program tries to use the value
    \\
    Number of processes in $x$, $y$ and $z$ direction does not match total number of Processes
&
Program terminates with an error message to \texttt{std::cerr}.
    \\
    $2^{s-1}$ or $c_x$ or $c_y$ does not evenly divide $N_x$ and $N_y$, where $s$ is the number of stages in the multigrid algorithm.
&
Program terminates on thrown error. Make sure the numbers add up.
    \\
    Number of processes in $x$, $y$ and $z$ direction does not evenly divide or is greater or equal $N_x/2^{s-1}$, $N_y/2^{s-1}$ and $N_z$, where $s$ is the number of stages in the multigrid algorithm.
&
Program terminates on failed assert
    \\
An MPI error occurs
&
Program crashes horribly printing cryptic error messages (stack trace) to \texttt{std::cerr}
    \\
A numerical instability occurs
&
The program terminates usually caused by a NaN exception raised. However,
the cause for the instability has to be determined inspecting the
last output in the output file.
    \\
\qquad large fieldaligned oscillations in $u_{\parallel,e}$ paired with instability in the edge of the box
&
Apply damping region
    \\
\qquad Perpendicular grid oscillations in $u_{\parallel,e}$ and $\Delta_\perp \phi$ in the damping region, symmetric in $\varphi$
&
Increase damping $alpha$, increase damping boundary, make the box larger/smaller, increasing DS refinement might help.
    \\
\qquad Spike in $u_{\parallel,e}$ shortly after simulation start
&
Increase $\nu_\perp$, increase $N_x$, $N_y$, decrease perturbation amplitude
    \\
\qquad Grid oscillations far away from the edge
&
Probably caused by the perpendicular transport that goes unstable. Increase $\nu_\perp$ and/or $N_x$, $N_y$. Increasing DS refinement might also help.
\\
\qquad Oscillations where fieldlines intersect the wall
&
Caused by boundary conditions in FCI method and necessarily underresolved toroidal direction.
Increase $N_z$, decrease $N_x$, $N_y$ or decrease $q$ value by decreasing $\mathcal P_\psi$ in geometry input file
\\
\bottomrule
\end{longtable}

%..................................................................
\bibliography{../../doc/related_pages/references}
%..................................................................

\end{document}