\section{Future Work}\label{sec:future-work}
The implementation of the proposed design is working and it can already handle quite a lot of nodes as the analysis part has shown. Due to the lack of more time not everything that has been proposed in the design chapter could be implemented. Based on the insights of the analysis also some parts of the design have to be improved.
Besides optimising the implementation and design, future work also proposes possible extensions of the \gls{mitosis} SDK.

\paragraph{Multi Cluster Support}
The implementation has shown how one cluster can scale up and how it behaves under various conditions. Yet, a cluster can only absorb a certain number of peers. The final size can be controlled with the \gls{ttl} of the \routerAlive message and the connection limits. In order to scale beyond the capabilities of a single cluster, the implementation has to support the coexistence of multiple clusters. There must be mechanisms for creating clusters, for closing abandoned clusters and for load balancing between them. The proposed design and implementation have been referred to as \gls{mitosis}: the envisioned process of dividing clusters into two and reassigning peers based on router proximity. This process has not been included in the implementation yet, but poses a challenging task for future research in this field.

\paragraph{Inter Cluster Communication}
When having multiple clusters the communication from on cluster to another becomes a challenge. One possible approach to solve inter cluster communication would be to introduce a \glsfirst{dht} based on Kademlia. Each node would need a unique identity. When a node enters the network it is assigned to a router. The id of the node would be stored in the Kademlia \gls{dht} as a key and the id of the router would be the value belonging to the key.

Mitosis already ensures that a peer can always exchange messages with the router it is assigned to. Also it ensures that a router knows all nodes within its own cluster.

Thus when a peer would want to communicate with a peer from another cluster it would address its message first to its router. As the peer is not in the cluster of the router, the router would then make a key look up in the Kademlia \gls{dht} for the key of the addressed peer id. Through the XOR-Metric the look up would return the value for the given key when the peer exists somewhere in the network. The value would be the id of the responsible router for the addressed peer.
The router would then make a node look up to find the router that has been returned by the key look up. The message is then redirected to the router that is returned by the node look up. This router in turn can send the message to the addressed peer as it has to exist within its cluster.
Example: A message from a node in cluster $\ X $ $\ Node A_X $ to a node in cluster $\ Y $ $\ Node B_Y $ would be routed as:
$\ Node A_X \rightarrow Router_X \rightarrow Router_Y \rightarrow Node B_Y $

\paragraph{Improving the peer selection metrics}
Each peer is acquiring new peers in order to full fill its connection goal. For the acquisition process a peer select suitable peers from its direct neighbours and ranks them based on a variety of metrics. The ranking of the peers has a significant influence on the stability of the whole network. But not only does it affect the overlay network but it is also lays the foundation for the streaming quality. The better the peers are selected the better the streaming quality can be.
WebRTC provides an extensive statistics API to gather information about codec information, dropped frames and jitter of an ongoing streaming session between to peers. Those information could be used as an extension of the existing metrics of Mitosis.
But not only connection related metrics could be improved also other metrics like uptime and reliability of a client could be added.

\paragraph{Improving the streaming graph}
To propagate the live stream through the network Mitosis has two phases: phase 1, where the stream is actively pushed from one peer to its two best neighbours and phase 2, where clients who haven't been selected pull the stream from peers that are providers.
However, results of the analysis have shown that the push phase is too aggressive and therefore it results in an unbalanced sub optimal tree. For the quality of the stream it is better to be as close to the source as possible.
Thus the push phase has to be limited to a certain extend in order to get a better tree.
Also the peer-churn problem it not solved optimal. Peers are recovering from a leaving node but it takes time until the stream connection to another provider is established. As an improvement, at least one fallback connection has to be established to a sibling of the parent node, in order to switch the stream with a minimal disruption of the playback.

\paragraph{Security Aspects}
As discussed in \vref{sec:security-integrity}, the current implementation of Mitosis does not warrant integrity of node identities. For use in a publicly released application, the node identity creation would have to be secured with a cryptographic proof of work to protect against spamming and flooding. This would also incentivise nodes to hold on to their identity and would allow nodes to build up a reputation within the network. Nodes could then use their persistent identity to secure \gls{dtls} connections. Given certainty on the communication partner's identity, applications could integrate private messaging and private video channels with end–to–end encryption. The persistent identity would be also a must have requirement for the Inter Cluster Communication approach with Kademlia.

\paragraph{Improved Signalling}
Currently there is only one signal server and the current implementation only allows one router. In a multi router scenario the signal would have to deal with load balancing. But not only load balancing becomes interesting but also geografically local awareness. In a optimal scenario the signal would put all geographically nearby nodes into one cluster. The geographical location of a node can be obtained by the signal server through the ip-address of the node.
Also to improve the ingress rate of peers into the network, the implementation should support multiple signal servers. This would also improve fault tolerance and would make it harder to shut down the network.

\paragraph{Media Persistence}
For use cases where live streaming is not enough and the content has to be persisted support for the \glsfirst{ipfs} could be integrated. By using \gls{ipfs} the distributed paradagim would not be interfered but only extended with a distributed persistence layer.
By using the MediaStream Recording API of the browser \cite{media-recorder-api} the stream can be chunked into segments and each segment can be added into \gls{ipfs}. In fact, IPFS provides a working example how IPFS could be use to realise a \gls{vod} streaming application using their protocol \cite{js-ipfs-video-streaming}.


\chapter{Kinetic equations}

The \sfincs~code is capable of solving many different variants of the drift-kinetic equation.
In this section we summarize the most common drift-kinetic equations
which can be solved with the code, giving the associated input parameters
(which are all in the  {\ttfamily \hyperref[sec:physicsParameters]{physicsParameters}} namelist.)
For other choices of these input parameters,
other combinations of terms in the drift-kinetic equation can be used than those
given here.
For more information, see section \ref{sec:trajectoryModels}, section \ref{sec:qn}, section \ref{sec:magneticDrifts},
and the version 3 technical documentation.
The following terms are always included in \sfincs:
parallel streaming, the magnetic mirror force, the collision operator,
and the inhomogeneous drive term from radial gradients.
Other terms generally can be turned on and off as desired using parameters in the
{\ttfamily \hyperref[sec:physicsParameters]{physicsParameters}} namelist.

Throughout this section, gradients and other partial derivatives are taken
at constant $x_s = v/\sqrt{2T_s/m_s}$ and at constant $\xi = v_{||} / v$, unless denoted otherwise with subscripts.
We use $s$ to denote the species, $r$ to denote any radial coordinate, (expressions are independent
of the specific radial coordinate used,)
$C_s$ to denote the collision operator, and $S_s$ to denote the source-sink term.
The magnetic moment is $\mu = v_{\perp}^2/\left(2 B\right)$ and the total energy is $W_s = v^2 / 2 + Z_s e \Phi / m_s$,
with the electrostatic potential $\Phi$.
A more detailed discussion of the equations implemented in the code can be found
in the technical documentation for \sfincs~version 3, available in the {\ttfamily /doc} directory
of the repository.

\section{System of equations}
Although the prime function of \sfincs~is to solve the drift-kinetic equation, when run in its most general way (\parlink{includePhi1} = \true and \parlink{readExternalPhi1} = \false) it simultaneously also solves the following equations:
\begin{align}
%\begin{equation}
%\begin{dcases}
	& \lambda + \sum_s Z_s \int d^3 v \, \left(f_{s 0} + f_{s 1} \right) = 0 \;\;\; (\mathrm{quasineutrality}), \label{eq:QuasineutralityEq}\\ %\nonumber \\
	%
	& %\left\langle \int d^3 v \, f_s \right\rangle = n_{0 s} \left(\psi\right),
	\left\langle \int d^3 v \, f_{s 1} \right\rangle = 0,
	\label{eq:DensityEq}\\ %\nonumber \\
	%
	& %\left\langle \frac{m_s}{3} \int d^3 v \, v^2 \, f_s \right\rangle = n_{0 s} \left(\psi\right) T_s \left(\psi\right),
	\left\langle \int d^3 v \, v^2 \, f_{s 1} \right\rangle = 0,
	\label{eq:EnergyEq}\\
	& \left\langle \Phi_1 \right\rangle = 0. \label{eq:Phi1Eq}
%\label{eq:SystemOfEquations}
%\end{dcases}
%\end{equation}
\end{align}
If $\Phi_1$ is not included (\parlink{includePhi1} = \false) or if it is read from a file (\parlink{readExternalPhi1} = \false) then Eqs.~\eqref{eq:QuasineutralityEq} and \eqref{eq:Phi1Eq} are not solved.
The unknowns in the system which are calculated are $\left\{f_{s1} \left(\theta, \zeta, x, \xi\right), \Phi_1 \left(\theta, \zeta\right), S_{s 1}, S_{s 2}, \lambda\right\}$ for the full system, and $\left\{f_{s1} \left(\theta, \zeta, x, \xi\right), S_{s 1}, S_{s 2}\right\}$ if $\Phi_1$ is not an unknown.
The potential variation is defined through $\Phi = \Phi_0 + \Phi_1$, where $\Phi_0 = \Phi_0\left(r\right) = \left\langle \Phi \right\rangle$ and $\Phi_1 = \Phi_1\left(\theta, \zeta\right)$ with $\left|\Phi_1\right| \ll \left|\Phi_0\right|$ (the variation of the electrostatic potential along flux-surfaces is also assumed to be small compared to the radial variation).
This implies that the radial electric field is $E_r = - d\Phi_0/dr$ (see \parlink{Er}).
$S_{s 1}$ and $S_{s 2}$ represent the source-sink term (see section \ref{sec:source-sink}), and $\lambda$ (\parlink{lambda}) is a Lagrange multiplier which should come out as negligible in quasineutrality.
We note that the number of degrees of freedom for the system is\newline
\Ntheta~$\times$~\Nzeta~$\times$~\Nx~$\times$~\Nxi~$\times$~\parlink{Nspecies}~+~\Ntheta~$\times$~\Nzeta~+~2~$\times$~\parlink{Nspecies}~+~1\newline
when $\Phi_1$ is included as an unknown and otherwise\newline
\Ntheta~$\times$~\Nzeta~$\times$~\Nx~$\times$~\Nxi~$\times$~\parlink{Nspecies}~+~2~$\times$~\parlink{Nspecies}.

\todo{It seems like Eqs.~\eqref{eq:DensityEq} and \eqref{eq:EnergyEq} are different for PAS}

\section{$0^{\mathrm{th}}$ order distribution}
The lowest-order distribution function is either a Maxwellian flux function $\displaystyle f_{s0}\left(r\right) = f_{sM}\left(r\right) = n_{s 0}\left(r\right) \left(\frac{m_s}{2 \pi T_s}\right)^{3/2} \exp \left(- x^2\right)$ if \parlink{includePhi1} = \false,
or contains the flux-surface variation $\displaystyle f_{s0}\left(r,\theta,\zeta\right) = f_{sM}\left(r\right) \exp \left[- Z_s e \Phi_1(\theta,\zeta) / T_s \right]$ if \parlink{includePhi1} = \true.
Here $n_{s 0}$ represents the input density given by \parlink{nHats}.
Note that in a calculation with \parlink{includePhi1} = \true, although $n_{s 0}\left(r\right)$ is a flux function it is not neccessarily equal to the flux-surface-averaged lowest-order density (given by $\left\langle \int f_{s 0} \, d^3v \right\rangle$) since the condition $\displaystyle \left\langle \Phi_1 \right\rangle = 0$ does not imply that $\displaystyle \left\langle \exp \left(- Z_s e \Phi_1 / T_s \right) \right\rangle = 1$.

\section{Collision operator}
\label{sec:CollisionOperator}
The total collision operator is a sum of linearized collision operators with each species:
%\begin{equation}
$ \displaystyle
C_s\left[f_s\right] \equiv \sum_b C_{s b}^{l}\left[f_s, f_b\right],
$
%\label{eq:CollisionOperatorTot}
%\end{equation}
where
%\begin{equation}
$ \displaystyle
C_{sb}^{l}\left[f_s, f_b\right] \equiv C_{s b}\left[f_{s 1}, f_{b M}\right] + C_{s b}\left[f_{s M}, f_{b 1}\right]
$
%\label{eq:LinearizedCollisionOperator}
%\end{equation}
and $C_{s b}\left[f_{s}, f_{b}\right]$ is the Fokker-Planck collision operator.
$C_{s b}\left[f_{s 1}, f_{b M}\right]$ %in Eq.~\eqref{eq:LinearizedCollisionOperator}
is referred to as the test particle part
and $C_{a b}\left[f_{a M}, f_{b 1}\right]$ is the field particle part.
The linearized collision operator may be written as
%\begin{equation}
$ \displaystyle
C_{a b}^{l} = C_{a b}^{L} + C_{a b}^{E} + C_{a b}^{F},
$
%\label{eq:LinearizedCollisionOperatorParts}
%\end{equation}
where $C_{a b}^{L} + C_{a b}^{E}$ together represent the test particle part and $C_{a b}^{F}$ the field particle part.
Running \sfincs~with \parlink{collisionOperator}~=~1 only the Lorentz part $C_{a b}^{L}$ is kept and $C_{a b}^{E} = C_{a b}^{F} = 0$,
whereas when \parlink{collisionOperator}~=~0 all three terms in $C_{a b}^{l}$ are kept.
A specification of the three terms and a more detailed description can be found in Appendix~A of \cite{Mollen2015} (and in the technical documentation).

Note that even if \parlink{includePhi1} = \true, the default collision operator is defined without the flux-surface variation, i.e. with respect to $f_{sM}\left(r\right)$ instead of $\displaystyle f_{s0}\left(r,\theta,\zeta\right) = f_{sM}\left(r\right) \exp \left[- Z_s e \Phi_1(\theta,\zeta) / T_s \right]$.
To include the variation, and use
$ \displaystyle
C_{sb}^{l}\left[f_s, f_b\right] \equiv C_{s b}\left[f_{s 1}, f_{b 0}\right] + C_{s b}\left[f_{s 0}, f_{b 1}\right],
$
set\newline \parlink{includePhi1InCollisionOperator} = \true (this is not default in \sfincs~because the memory and time requirements can increase significantly but the effect is usually small).
It is also possible to include the temperature equilibration term $C_{ab}[ f_{aM}, f_{bM}]$ in the collision operator (or $C_{ab}[ f_{a0}, f_{b0}]$ if \parlink{includePhi1InCollisionOperator} = \true) by using\newline \parlink{includeTemperatureEquilibrationTerm} = \true, but this term does not directly give any parallel or radial transport.

\section{Source-sink term}
\label{sec:source-sink}
\todo{Can Matt check this section?}\newline
The source-sink term $S_s$ is introduced together with the constraints given by Eqs.~\eqref{eq:DensityEq} and \eqref{eq:EnergyEq} to ensure that a steady-state solution exists.
This term is controlled by \parlink{constraintScheme}.
The default (recommended) setting \parlink{constraintScheme} = -1 implies that $S_s = \left(a_2 x^2 + a_0\right) e^{-x^2}$ represents a particle and heat source if the Fokker-Planck collision operator is used (\parlink{collisionOperator} = 0), where the coefficients $a_0$ and $a_2$ are calculated in the simulation (see \parlink{sources}).
\newline\todo{Can Matt explain what is calculated when pitch-angle-scattering is used?}\newline
Note that $\Phi_1$ is never included in the source-sink term irrespective of the type of calculation.

\section{Description of various drift-kinetic equations}
\label{sec:DKequations}

Here we describe the most common forms of the drift-kinetic equation and their settings in \sfincs.
A more detailed description of the different forms can be found in \cite{sfincsPaper}, and in \cite{Mollen2018} for calculations including $\Phi_1$.
The total drift velocity is $\vect{v}_{ds} = \vect{v}_{ms} + \vect{v}_{E}$, i.e. the sum of the magnetic drift velocity $\vect{v}_{ms}$ and the $\vect{E} \times \vect{B}$-drift velocity $\vect{v}_{E}$.
The radial magnetic drift is given by $\displaystyle \vect{v}_{ms} \cdot \nabla r = \left(m_s/Z_s e B^2\right) \left( v_{\perp}^2/2  + v_\|^2 \right) \vect{b}~\times~\nabla B~\cdot~\nabla r$.
The poloidal and toroidal magnetic drifts are set by \parlink{magneticDriftScheme}.
The $\vect{E} \times \vect{B}$-drift is $\vect{v}_E = \left(\vect{b} \times \nabla \Phi \right) / B$, and its radial part is only present if $\Phi_1$ is included $\displaystyle \vect{v}_{E} \cdot \nabla r = \left(\vect{b} \times \nabla \Phi_1 \cdot \nabla r\right) / B$

\subsection{Default: Full $\vect{E}\times\vect{B}$ trajectories; no poloidal or toroidal magnetic drifts; flux function potential}

\begin{eqnarray}
&&\left(v_{||}\vect{b} + \frac{d\Phi_0}{dr} \frac{1}{B^2} \vect{B}\times\nabla r \right) \cdot \nabla f_{s1} \\
&&+ \left[ - \frac{(1-\xi^2)v}{2B} \nabla_{||} B
+\frac{(1-\xi^2)\xi}{2B^3} \frac{d\Phi_0}{dr}\vect{B}\times\nabla r\cdot\nabla B \right]
 \frac{\partial f_{s1}}{\partial \xi} \nonumber \\
&&-(\vect{v}_{ms} \cdot\nabla r) \frac{Z_s e}{2 T_s x_s} \frac{d\Phi_0}{dr} \frac{\partial f_{s1}}{\partial x_s} \nonumber \\
&&+ (\vect{v}_{ms} \cdot \nabla r) \left[ \frac{1}{n_s} \frac{dn_s}{dr} + \frac{Z_s e}{T_s} \frac{d\Phi_0}{dr} + \left(x_s^2-\frac{3}{2}\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{sM}
 = C_s + S_s \nonumber
\end{eqnarray}
Note that this equation is equivalent to the following one, in which the independent variables
are $(\mu,v_{||})$ instead of $(\xi,x_s)$:
\begin{eqnarray}
&&\left(v_{||}\vect{b} + \frac{d\Phi_0}{dr} \frac{1}{B^2} \vect{B}\times\nabla r \right) \cdot (\nabla f_{s1})_{\mu, v_{||}} \\
&&+ \left[ - \mu \nabla_{||} B
-\frac{v_{||}}{B^2} \frac{d\Phi_0}{dr} \vect{b}\times\nabla B \times \nabla r \right]
\left( \frac{\partial f_{s1}}{\partial v_{||}} \right)_{\mu} \nonumber \\
&& + (\vect{v}_{ms} \cdot \nabla r) \left[ \frac{1}{n_s} \frac{dn_s}{dr} + \frac{Z_s e}{T_s} \frac{d\Phi_0}{dr} + \left(x_s^2-\frac{3}{2}\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{sM}
=C_s + S_s \nonumber
\end{eqnarray}
These equivalent forms of the kinetic equation are selected using \\
\parlink{includeXDotTerm} = \true  \;\;\; (Default) \\
\parlink{includeElectricFieldTermInXiDot} = \true \;\;\; (Default) \\
\parlink{useDKESExBDrift} = \false \;\;\; (Default) \\
\parlink{magneticDriftScheme} = 0 \;\;\; (Default) \\
\parlink{includePhi1} = \false \;\;\; (Default) %\\
%\parlink{includeRadialExBDrive} = \false \;\;\; (Default) \\
%\parlink{nonlinear} = \false \;\;\; (Default)

\subsection{DKES $\vect{E}\times\vect{B}$ trajectories; no poloidal or toroidal magnetic drifts; flux function potential}

This form of the kinetic equation is useful for benchmarking with DKES and other codes
that use the same equation.

\begin{eqnarray}
&&\left(v_{||}\vect{b} + \frac{d\Phi_0}{dr} \frac{1}{\left< B^2\right>} \vect{B}\times\nabla r \right) \cdot \nabla f_{s1} \\
&& - \frac{(1-\xi^2)v}{2B} (\nabla_{||} B)
 \frac{\partial f_{s1}}{\partial \xi} \nonumber \\
&&+ (\vect{v}_{ms} \cdot \nabla r) \left[ \frac{1}{n_s} \frac{dn_s}{dr} + \frac{Z_s e}{T_s} \frac{d\Phi_0}{dr} + \left(x_s^2-\frac{3}{2}\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{sM}
 = C_s + S_s \nonumber
\end{eqnarray}
This form of the kinetic equation is selected using \\
\parlink{includeXDotTerm} = \false  \;\;\; (Not default) \\
\parlink{includeElectricFieldTermInXiDot} = \false \;\;\; (Not default) \\
\parlink{useDKESExBDrift} = \true \;\;\; (Not default) \\
\parlink{magneticDriftScheme} = 0 \;\;\; (Default) \\
\parlink{includePhi1} = \false \;\;\; (Default) %\\
%\parlink{includeRadialExBDrive} = \false \;\;\; (Default) \\
%\parlink{nonlinear} = \false \;\;\; (Default)

\subsection{Full $\vect{E}\times\vect{B}$ trajectories; including poloidal and toroidal magnetic drifts; flux function potential}

\begin{eqnarray}
&&\left(v_{||}\vect{b} + \frac{d\Phi_0}{dr} \frac{1}{B^2} \vect{B}\times\nabla r  + \vect{v}_{ms}\right) \cdot \nabla \theta \frac{\partial f_{s1}}{\partial \theta} \\
&&\left(v_{||}\vect{b} + \frac{d\Phi_0}{dr} \frac{1}{B^2} \vect{B}\times\nabla r  + \vect{v}_{ms}\right) \cdot \nabla \zeta \frac{\partial f_{s1}}{\partial \zeta} \nonumber \\
&&+ \left\{ - \frac{(1-\xi^2)v}{2B} \nabla_{||} B
+\frac{(1-\xi^2)\xi}{2B^3} \frac{d\Phi_0}{dr}\vect{B}\times\nabla r\cdot\nabla B \right. \nonumber \\
&& \left. \hspace{0.25in} -\frac{T_s x_s^2 (\nabla r\cdot\nabla\theta\times\nabla\zeta)}{Z_s e B^3} (1-\xi^2)\xi
\left[ \left( \frac{\partial B_r}{\partial \zeta} - \frac{\partial B_\zeta}{\partial r}\right)\frac{\partial B}{\partial\theta}
+ \left(\frac{\partial B_\theta}{\partial r} - \frac{\partial B_r}{\partial\theta}\right) \frac{\partial B}{\partial\zeta}\right]
\right\}
 \frac{\partial f_{s1}}{\partial \xi} \nonumber \\
&&-(\vect{v}_{ms} \cdot\nabla r) \frac{Z_s e}{2 T_s x_s} \frac{d\Phi_0}{dr} \frac{\partial f_{s1}}{\partial x_s} \nonumber \\
&&+ (\vect{v}_{ms} \cdot \nabla r) \left[ \frac{1}{n_s} \frac{dn_s}{dr} + \frac{Z_s e}{T_s} \frac{d\Phi_0}{dr} + \left(x_s^2-\frac{3}{2}\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{sM}
 = C_s + S_s \nonumber
\end{eqnarray}
Notice the magnetic drifts affect the coefficients of $\partial f_{s1}/\partial \theta$, $\partial f_{s1}/\partial \zeta$,
and $\partial f_{s1}/\partial \xi$,
but there is no change to the coefficient of $\partial f_{s1}/\partial x_s$.
This form of the kinetic equation is selected using \\
\parlink{includeXDotTerm} = \true  \;\;\; (Default) \\
\parlink{includeElectricFieldTermInXiDot} = \true \;\;\; (Default) \\
\parlink{useDKESExBDrift} = \false \;\;\; (Default) \\
\parlink{magneticDriftScheme} = 1 \;\;\; (Not default) \\
\parlink{includePhi1} = \false \;\;\; (Default) %\\
%\parlink{includeRadialExBDrive} = \false \;\;\; (Default) \\
%\parlink{nonlinear} = \false \;\;\; (Default)

%%THE EQUATIONS IN THE FOLLOWING SUBSECTION WAS BASED ON J M García-Regaña et al 2013 Plasma Phys. Control. Fusion 55 074008
%%HOWEVER, THESE EQUATIONS ARE NOT COMPLETELY CORRECT, AND CAN NO LONGER BE USED IN SFINCS
%\subsection{Full $\vect{E}\times\vect{B}$ trajectories; no poloidal or toroidal magnetic drifts; leading $\Phi_1$ term}
%
%In this form of the drift-kinetic equation, we include the largest term involving $\Phi_1$,
%associated with the adiabatic response.
%However, other terms considered in Ref \cite{Regana2017} are not included.
%
%\begin{eqnarray}
%&&\left(v_{||}\vect{b} + \frac{d\Phi_0}{dr} \frac{1}{B^2} \vect{B}\times\nabla r \right) \cdot \nabla f_{s1} \\
%&&+ \left[ - \frac{(1-\xi^2)v}{2B} \nabla_{||} B
%+\frac{(1-\xi^2)\xi}{2B^3} \frac{d\Phi_0}{dr}\vect{B}\times\nabla r\cdot\nabla B \right]
% \frac{\partial f_{s1}}{\partial \xi} \nonumber \\
%&&-(\vect{v}_{ms} \cdot\nabla r) \frac{Z_s e}{2 T_s x_s} \frac{d\Phi_0}{dr} \frac{\partial f_{s1}}{\partial x_s} \nonumber \\
%&&+\frac{Z_s e}{T_s} f_{sM} v_{||} \nabla_{||} \Phi_1 \nonumber \\
%&&+ (\vect{v}_{ms} \cdot \nabla r) \left[ \frac{1}{n_s} \frac{dn_s}{dr} + \frac{Z_s e}{T_s} \frac{d\Phi_0}{dr} + \left(x_s^2-\frac{3}{2}\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{sM}
% = C_s + S_s \nonumber
%\end{eqnarray}
%Note that this equation is equivalent to the following one, in which the independent variables
%are $(\mu,v_{||})$ instead of $(\xi,x_s)$:
%\begin{eqnarray}
%&&\left(v_{||}\vect{b} + \frac{d\Phi_0}{dr} \frac{1}{B^2} \vect{B}\times\nabla r \right) \cdot (\nabla f_{s1})_{\mu, v_{||}} \\
%&&+ \left[ - \mu \nabla_{||} B
%-\frac{v_{||}}{B^2} \frac{d\Phi_0}{dr} \vect{b}\times\nabla B \times \nabla r \right]
%\left( \frac{\partial f_{s1}}{\partial v_{||}} \right)_{\mu} \nonumber \\
%&&+\frac{Z_s e}{T_s} f_{sM} v_{||} \nabla_{||} \Phi_1 \nonumber \\
%&& + (\vect{v}_{ms} \cdot \nabla r) \left[ \frac{1}{n_s} \frac{dn_s}{dr} + \frac{Z_s e}{T_s} \frac{d\Phi_0}{dr} + \left(x_s^2-\frac{3}{2}\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{sM}
%=C_s + S_s \nonumber
%\end{eqnarray}
%These equivalent forms of the kinetic equation are selected using \\
%\parlink{includeXDotTerm} = \true  \;\;\; (Default) \\
%\parlink{includeElectricFieldTermInXiDot} = \true \;\;\; (Default) \\
%\parlink{useDKESExBDrift} = \false \;\;\; (Default) \\
%\parlink{magneticDriftScheme} = 0 \;\;\; (Default) \\
%\parlink{includePhi1} = \true \;\;\; (Not default) %\\
%%\parlink{includeRadialExBDrive} = \false \;\;\; (Default) \\
%%\parlink{nonlinear} = \false \;\;\; (Default)

\subsection{Full $\vect{E}\times\vect{B}$ trajectories; no poloidal or toroidal magnetic drifts; Garc\'{i}a-Rega\~{n}a $\Phi_1$ terms}

%This form of the drift-kinetic equation is nearly identical to equation (11) in Ref \cite{Regana2017}.
%The one difference (which should be small) is that at the end of (11), Garc\'{i}a-Rega\~{n}a
%has a term $\propto \vect{v}_m \cdot \nabla \Phi_1$, which is not (yet) in \sfincs.

This form of the drift-kinetic equation is studied in Ref.~\cite{Mollen2018} (Eq.~(6)) and in Ref.~\cite{Regana2017} (Eq.~(16)).

\todo{In Eq. below check terms in left-hand-side multiplying $\frac{\partial f_{s1}}{\partial \xi}$ and $\frac{\partial f_{s1}}{\partial x_s}$. Define $v_s$?}\newline

\begin{eqnarray}
&&\left(v_{||}\vect{b} + \frac{d\Phi_0}{dr} \frac{1}{B^2} \vect{B}\times\nabla r \right) \cdot \nabla f_{s1} \\
&&+ \left[ - \frac{(1-\xi^2)v}{2B} \nabla_{||} B
+\frac{(1-\xi^2)\xi}{2B^3} \frac{d\Phi_0}{dr}\vect{B}\times\nabla r\cdot\nabla B
-\frac{Z_s e}{v m_s}(1-\xi^2)(\nabla_{||}\Phi_1)
\right]
 \frac{\partial f_{s1}}{\partial \xi} \nonumber \\
&&+ \left[
-(\vect{v}_{ms} \cdot\nabla r) \frac{Z_s e}{2 T_s x_s} \frac{d\Phi_0}{dr}
-\frac{Z_s e \xi}{v_s m_s}
\right] \frac{\partial f_{s1}}{\partial x_s} \nonumber \\
%&&+\frac{Z_s e}{T_s} f_{sM} v_{||} \nabla_{||} \Phi_1 \nonumber \\
%&& + (\vect{v}_E \cdot \nabla r) \left[ \frac{1}{n_s} \frac{dn_s}{dr}  + \left(x_s^2-\frac{3}{2}\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{sM} \nonumber \\
&&+ \left(\vect{v}_{ms} + \vect{v}_E\right) \cdot \nabla r \left[ \frac{1}{n_{s 0}} \frac{dn_{s 0}}{dr} + \frac{Z_s e}{T_s} \frac{d\Phi_0}{dr} + \left(x_s^2 - \frac{3}{2} + \frac{Z_s e}{T_s}\Phi_1\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{s0}
 = C_s + S_s \nonumber
\end{eqnarray}
Here $\displaystyle f_{s0} = f_{s0}\left(r,\theta,\zeta\right) = f_{sM}\left(r\right) \exp \left[- Z_s e \Phi_1(\theta,\zeta) / T_s \right]$,
whereas $n_{s 0} = n_{s 0} \left(r\right)$ represents the input density given by \parlink{nHats}.
Note that this equation is equivalent to the following one, in which the independent variables
are $(\mu,v_{||})$ instead of $(\xi,x_s)$:
\begin{eqnarray}
&&\left(v_{||}\vect{b} + \frac{d\Phi_0}{dr} \frac{1}{B^2} \vect{B}\times\nabla r \right) \cdot (\nabla f_{s1})_{\mu, v_{||}} \\
&&+ \left[ -\frac{Z_s e}{m_s} \nabla_{||} \Phi_1
- \mu \nabla_{||} B
-\frac{v_{||}}{B^2} \frac{d\Phi_0}{dr} \vect{b}\times\nabla B \cdot \nabla r \right]
\left( \frac{\partial f_{s1}}{\partial v_{||}} \right)_{\mu} \nonumber \\
%&&+\frac{Z_s e}{T_s} f_{sM} v_{||} \nabla_{||} \Phi_1 \nonumber \\
%&& + (\vect{v}_E \cdot \nabla r) \left[ \frac{1}{n_s} \frac{dn_s}{dr}  + \left(x_s^2-\frac{3}{2}\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{sM} \nonumber \\
&& + \left(\vect{v}_{ms} + \vect{v}_E\right) \cdot \nabla r  \left[ \frac{1}{n_{s 0}} \frac{dn_{s 0}}{dr} + \frac{Z_s e}{T_s} \frac{d\Phi_0}{dr} + \left(x_s^2-\frac{3}{2} + \frac{Z_s e}{T_s}\Phi_1\right) \frac{1}{T_s} \frac{dT_s}{dr}\right] f_{s0}
=C_s + S_s \nonumber
\end{eqnarray}
These equivalent forms of the kinetic equation are selected using \\
\parlink{includeXDotTerm} = \true  \;\;\; (Default) \\
\parlink{includeElectricFieldTermInXiDot} = \true \;\;\; (Default) \\
\parlink{useDKESExBDrift} = \false \;\;\; (Default) \\
\parlink{magneticDriftScheme} = 0 \;\;\; (Default) \\
\parlink{includePhi1} = \true \;\;\; (Not default) %\\
%\parlink{includeRadialExBDrive} = \true \;\;\; (Not default) \\
%\parlink{nonlinear} = \true \;\;\; (Not default)

\section{Inductive electric field}
\label{sec:Inductive-electric-field}
Besides the terms described above, \sfincs~has the possibility to include an inductive parallel electric field in the drive part of the kinetic equation. There is typically no inductive electric field in a stellarator, but the term is retained since the transport driven by the inductive electric field is used for computing monoenergetic transport coefficients, and thus for comparison with other codes such as \dkes. This term has the form $\displaystyle \frac{Z_s e}{T_s} v_\| \frac{\left\langle \vect{E} \cdot \vect{B}\right\rangle B}{\left\langle B^2\right\rangle} f_{sM}$ and is set by \parlink{EParallelHat} (i.e. if non-zero than this term is added to the right-hand-side of all kinetic equations in Sec.~\ref{sec:DKequations}).
Also see the input parameter \parlink{EParallelHatSpec}.


\chapter{OClinECore}

Taken from the OCLinECore example page

\begin{oclinecore}
    import ecore : 'http://www.eclipse.org/emf/2002/Ecore#/';

    package tutorial : tut = 'http://www.eclipse.org/mdt/ocl/oclinecore/tutorial'
    {
        class Library
        {
            attribute name : String;
            property books#_'library' : Book[*] { composes };
            property loans : Loan[*] { composes };
            property members#_'library' : Member[*] { composes };
        }

        class Book
        {
            invariant SufficientCopies:
                library.loans->select(book=self)->size() <= copies;
            attribute name : String;
            attribute copies : Integer;
            property _'library'#books : Library;
            property loans : Loan[*] { derived,volatile }
            {
                derivation: library.loans->select(book=self);
            }
            property _'library'#books : Library[?];
            operation isAvailable() : Boolean[?]
            {
                body: loans->size() < copies;
            }
        }

        class Member
        {
            attribute name : String;
            property _'library'#members : Library;
        }

        class Loan
        {
            property book : Book;
            property member : Member;
            attribute date : ecore::EDate;
        }
    }
\end{oclinecore}


\subsubsection{Cap Floor Volatility Structures}

The cap volatility structure parameterisation allows the user to pick out term cap volatilities in the market data and define how they should be stripped to create an optionlet volatility structure. The parameterisation allows for three separate types of input term cap volatility structures:

\begin{enumerate}
\item A strip of at-the-money (ATM) cap volatilities.
\item A cap maturity tenor by absolute cap strike grid of cap volatilities.
\item A combined structure containing both the ATM cap volatilities and the maturity by strike grid of cap volatilities.
\end{enumerate}

The input cap volatilities may be normal, lognormal or shifted lognormal. The structure of the market quotes is provided in Table \ref{tab:capfloor_implvol_quote}.

The structure of the XML, i.e.\ the nodes that are necessary, used and ignored, and the way that the optionlet volatilities are stripped hinges on the value of the \lstinline!InterpolateOn! node. This node may be set to \lstinline!TermVolatilities! or \lstinline!OptionletVolatilities!.

When set to \lstinline!TermVolatilities!, a column of sequential caps or floors, are created for each strike level out to the maximum cap maturity configured. In other words, if the index tenor is 6M, the first cap created would have a maturity of 1Y, the second cap 18M, the third cap 2Y and so on until we have a cap with maturity equal to the maximum maturity tenor in the configuration. The volatility for each of these caps or floors is then interpolated from the term cap volatility surface using the configured interpolation. Finally, the optionlet volatility at each cap or floor maturity, starting from the first, is derived in turn such that the column of cap or floor volatilities are matched.

When set to \lstinline!OptionletVolatilities!, the optionlet volatility structure pillar dates are set to the fixing dates on the last caplet on each of the configured caps or floors i.e.\ caps or floors with the maturities in the configured \lstinline!Tenors! or \lstinline!AtmTenors!. The optionlet volatilities on these pillar dates are then solved for such that the configured cap or floor volatilities are matched. In the following sections, we describe four XML configurations separately for clarity:

\begin{enumerate}
\item ATM curve with interpolation on term volatilities.
\item ATM curve with interpolation on optionlet volatilities.
\item Surface, possibly including an ATM column, with interpolation on term volatilities.
\item Surface, possibly including an ATM column, with interpolation on optionlet volatilities.
\end{enumerate}

Listing \ref{lst:capfloorvol_atm_configuration_term} shows the layout for parameterising an ATM cap volatility curve with interpolation on term volatilities. Nodes that have no effect for this parameterisation but that are allowed by the schema are not referenced. The meaning of each of the nodes is as follows:

\begin{itemize}
\item
\lstinline!CurveId!: Unique identifier for the cap floor volatility structure.

\item \lstinline!CurveDescription! [Optional]:
A description of the volatility structure. It is for information only and may be left blank.

\item \lstinline!VolatilityType!:
Indicates the cap floor volatility type. It may be \lstinline!Normal!, \lstinline!Lognormal! or \lstinline!ShiftedLognormal!. Note that this then determines which market data points are looked up in the market when creating the ATM cap floor curve and how they are interpreted when stripping the optionlets. In particular, the market will be searched for market data points of the form \lstinline!CAPFLOOR/RATE_NVOL/Currency/Tenor/IndexTenor/1/1/0!, \lstinline!CAPFLOOR/RATE_LNVOL/Currency/Tenor/IndexTenor/1/1/0! or \lstinline!CAPFLOOR/RATE_SLNVOL/Currency/Tenor/IndexTenor/1/1/0! respectively.

\item \lstinline!Extrapolation!:
Indicates the extrapolation in the time direction before the first optionlet volatility and after the last optionlet volatility. The extrapolation occurs on the stripped optionlet volatilities. The allowable values are \lstinline!None!, \lstinline!Flat! and \lstinline!Linear!. If set to \lstinline!None!, extrapolation is turned off and an exception is thrown if the optionlet surface is queried outside the allowable times. If set to \lstinline!Flat!, the first optionlet volatility is used before the first time and the last optionlet volatility is used after the last time. If set to \lstinline!Linear!, the interpolation method configured in \lstinline!InterpolationMethod! is used to extrapolate.

\item \lstinline!InterpolationMethod! [Optional]:
Indicates the interpolation in the time direction. As \lstinline!InterpolateOn! is set to \lstinline!TermVolatilities! here, the interpolation is used in the stripping process to interpolate the term cap floor volatility curve as explained above. It is also used to interpolate the optionlet volatilities when an optionlet volatility is queried from the stripped optionlet structure. The allowable values are \lstinline!Bilinear! and \lstinline!BicubicSpline!. If not set, \lstinline!BicubicSpline! is assumed. Obviously, as we are describing an ATM curve here, there is no interpolation in the strike direction so when \lstinline!Bilinear! is set the time interpolation is linear and when \lstinline!BicubicSpline! is set the time interpolation is cubic spline.

\item \lstinline!IncludeAtm!:
A boolean value indicating if an ATM curve should be used. Allowable boolean values are given in the Table \ref{tab:boolean_allowable}. As we are describing an ATM curve here, this node should be set to \lstinline!true! as shown in \ref{lst:capfloorvol_atm_configuration_term}.

\item \lstinline!DayCounter!:
The day counter used to convert from dates to times in the underlying structure. Allowable values are given in the Table \ref{tab:daycount}.

\item \lstinline!Calendar!:
The calendar used to advance dates by periods in the underlying structure. In particular, it is used in deriving the cap maturity dates from the configured cap tenors. Allowable values are given in the Table \ref{tab:calendar}.

\item \lstinline!BusinessDayConvention!:
The business day convention used to advance dates by periods in the underlying structure. In particular, it is used in deriving the cap maturity dates from the configured cap tenors. Allowable values are given in the Table \ref{tab:allow_stand_data} under \lstinline!Roll Convention!.

\item \lstinline!Tenors! [Optional]:
A comma separated list of valid tenor strings giving the cap floor maturity tenors to be used in the ATM curve. If omitted, the tenors for the ATM curve must be provided in the \lstinline!AtmTenors! node instead. If the tenors are provided here, the \lstinline!AtmTenors! node may be omitted.

\item \lstinline!IborIndex!:
A valid interest rate index name giving the index underlying the cap floor quotes. Allowable values are given in the Table \ref{tab:indices}.

\item \lstinline!DiscountCurve!:
A reference to a valid discount curve specification that will be used to discount cashflows during the stripping process. It should be of the form \lstinline!Yield/Currency/curve_name! where \lstinline!curve_name! is the name of a yield curve defined in the yield curve configurations.

\item \lstinline!AtmTenors! [Optional]:
A comma separated list of valid tenor strings giving the cap floor maturities to be used in the ATM curve. If omitted, the tenors for the ATM curve must be provided in the \lstinline!Tenors! node instead. If the tenors are provided here, the \lstinline!Tenors! node may be omitted.

\item \lstinline!SettlementDays! [Optional]:
Any non-negative integer is allowed here. If omitted, it is assumed to be 0. If provided the reference date of the term volatility curve and the stripped optionlet volatility structure will be calculated by advancing the valuation date by this number of days using the configured calendar and business day convention. In general, this should be omitted or set to 0.

\item \lstinline!InterpolateOn!:
As referenced above, the allowable values are \lstinline!TermVolatilities! or \lstinline!OptionletVolatilities!. As we are describing here an ATM curve with interpolation on term volatilities, this should be set to \lstinline!TermVolatilities! as shown in Listing \ref{lst:capfloorvol_atm_configuration_term}.

\item \lstinline!BootstrapConfig! [Optional]:
This node holds configuration details for the iterative bootstrap that are described in section \ref{sec:bootstrap_config}. If omitted, this node's default values described in section \ref{sec:bootstrap_config} are used.

\end{itemize}

\begin{longlisting}
\begin{minted}[fontsize=\footnotesize]{xml}
<CapFloorVolatility>
  <CurveId>...</CurveId>
  <CurveDescription>...</CurveDescription>
  <VolatilityType>...</VolatilityType>
  <Extrapolation>...</Extrapolation>
  <InterpolationMethod>...</InterpolationMethod>
  <IncludeAtm>true</IncludeAtm>
  <DayCounter>...</DayCounter>
  <Calendar>...</Calendar>
  <BusinessDayConvention>...</BusinessDayConvention>
  <Tenors>...</Tenors>
  <IborIndex>...</IborIndex>
  <DiscountCurve>...</DiscountCurve>
  <AtmTenors>...</AtmTenors>
  <SettlementDays>...</SettlementDays>
  <InterpolateOn>TermVolatilities</InterpolateOn>
  <BootstrapConfig>...</BootstrapConfig>
</CapFloorVolatility>
\end{minted}
\caption{ATM cap floor configuration with interpolation on term volatilities.}
\label{lst:capfloorvol_atm_configuration_term}
\end{longlisting}

Listing \ref{lst:capfloorvol_atm_configuration_opt} shows the layout for parameterising an ATM cap volatility curve with interpolation on optionlet volatilities. Nodes that have no effect for this parameterisation but that are allowed by the schema are not referenced. The meaning of each of the nodes is as follows:

\begin{itemize}
\item
\lstinline!CurveId!: Unique identifier for the cap floor volatility structure.

\item \lstinline!CurveDescription! [Optional]:
A description of the volatility structure. It is for information only and may be left blank.

\item \lstinline!VolatilityType!:
Indicates the cap floor volatility type. It may be \lstinline!Normal!, \lstinline!Lognormal! or \lstinline!ShiftedLognormal!. Note that this then determines which market data points are looked up in the market when creating the ATM cap floor curve and how they are interpreted when stripping the optionlets. In particular, the market will be searched for market data points of the form \lstinline!CAPFLOOR/RATE_NVOL/Currency/Tenor/IndexTenor/1/1/0!, \lstinline!CAPFLOOR/RATE_LNVOL/Currency/Tenor/IndexTenor/1/1/0! or \lstinline!CAPFLOOR/RATE_SLNVOL/Currency/Tenor/IndexTenor/1/1/0! respectively.

\item \lstinline!Extrapolation!:
The allowable values are \lstinline!None!, \lstinline!Flat! and \lstinline!Linear!. If set to \lstinline!None!, extrapolation is turned off and an exception is thrown if the optionlet surface is queried outside the allowable times. Otherwise, extrapolation is allowed and the type of extrapolation is determined by the \lstinline!TimeInterpolation! node value described below.

\item \lstinline!IncludeAtm!:
A boolean value indicating if an ATM curve should be used. Allowable boolean values are given in the Table \ref{tab:boolean_allowable}. As we are describing an ATM curve here, this node should be set to \lstinline!true! as shown in \ref{lst:capfloorvol_atm_configuration_opt}.

\item \lstinline!DayCounter!:
The day counter used to convert from dates to times in the underlying structure. Allowable values are given in the Table \ref{tab:daycount}.

\item \lstinline!Calendar!:
The calendar used to advance dates by periods in the underlying structure. In particular, it is used in deriving the cap maturity dates from the configured cap tenors. Allowable values are given in the Table \ref{tab:calendar}.

\item \lstinline!BusinessDayConvention!:
The business day convention used to advance dates by periods in the underlying structure. In particular, it is used in deriving the cap maturity dates from the configured cap tenors. Allowable values are given in the Table \ref{tab:allow_stand_data} under \lstinline!Roll Convention!.

\item \lstinline!Tenors! [Optional]:
A comma separated list of valid tenor strings giving the cap floor maturity tenors to be used in the ATM curve. If omitted, the tenors for the ATM curve must be provided in the \lstinline!AtmTenors! node instead. If the tenors are provided here, the \lstinline!AtmTenors! node may be omitted.

\item \lstinline!IborIndex!:
A valid interest rate index name giving the index underlying the cap floor quotes. Allowable values are given in the Table \ref{tab:indices}.

\item \lstinline!DiscountCurve!:
A reference to a valid discount curve specification that will be used to discount cashflows during the stripping process. It should be of the form \lstinline!Yield/Currency/curve_name! where \lstinline!curve_name! is the name of a yield curve defined in the yield curve configurations.

\item \lstinline!AtmTenors! [Optional]:
A comma separated list of valid tenor strings giving the cap floor maturities to be used in the ATM curve. If omitted, the tenors for the ATM curve must be provided in the \lstinline!Tenors! node instead. If the tenors are provided here, the \lstinline!Tenors! node may be omitted.

\item \lstinline!SettlementDays! [Optional]:
Any non-negative integer is allowed here. If omitted, it is assumed to be 0. If provided the reference date of the term volatility curve and the stripped optionlet volatility structure will be calculated by advancing the valuation date by this number of days using the configured calendar and business day convention. In general, this should be omitted or set to 0.

\item \lstinline!InterpolateOn!:
As referenced above, the allowable values are \lstinline!TermVolatilities! or \lstinline!OptionletVolatilities!. As we are describing here an ATM curve with interpolation on optionlet volatilities, this should be set to \lstinline!OptionletVolatilities! as shown in Listing \ref{lst:capfloorvol_atm_configuration_opt}.

\item \lstinline!TimeInterpolation! [Optional]:
Indicates the interpolation and extrapolation, if allowed by the \lstinline!Extrapolation! node, in the time direction. As \lstinline!InterpolateOn! is set to \lstinline!OptionletVolatilities! here, the interpolation is used to interpolate the optionlet volatilities only i.e.\ there is no interpolation on the term cap floor volatility curve. The allowable values are \lstinline!Linear!, \lstinline!LinearFlat!, \lstinline!BackwardFlat!, \lstinline!Cubic! and \lstinline!CubicFlat!. If not set, \lstinline!LinearFlat! is assumed. Note that \lstinline!Linear! indicates linear interpolation and linear extrapolation. \lstinline!LinearFlat! indicates linear interpolation and flat extrapolation. Analogous meanings apply for \lstinline!Cubic! and \lstinline!CubicFlat!.

\item \lstinline!BootstrapConfig! [Optional]:
This node holds configuration details for the iterative bootstrap that are described in section \ref{sec:bootstrap_config}. If omitted, this node's default values described in section \ref{sec:bootstrap_config} are used.

\end{itemize}

\begin{longlisting}
\begin{minted}[fontsize=\footnotesize]{xml}
<CapFloorVolatility>
  <CurveId>...</CurveId>
  <CurveDescription>...</CurveDescription>
  <VolatilityType>...</VolatilityType>
  <Extrapolation>...</Extrapolation>
  <IncludeAtm>true</IncludeAtm>
  <DayCounter>...</DayCounter>
  <Calendar>...</Calendar>
  <BusinessDayConvention>...</BusinessDayConvention>
  <Tenors>...</Tenors>
  <IborIndex>...</IborIndex>
  <DiscountCurve>...</DiscountCurve>
  <AtmTenors>...</AtmTenors>
  <SettlementDays>...</SettlementDays>
  <InterpolateOn>OptionletVolatilities</InterpolateOn>
  <TimeInterpolation>...</TimeInterpolation>
  <BootstrapConfig>...</BootstrapConfig>
</CapFloorVolatility>
\end{minted}
\caption{ATM cap floor configuration with interpolation on optionlet volatilities.}
\label{lst:capfloorvol_atm_configuration_opt}
\end{longlisting}

Listing \ref{lst:capfloorvol_surface_configuration_term} shows the layout for parameterising a cap tenor by absolute cap strike volatility surface with interpolation on term volatilities. This parameterisation also allows for the inclusion of a cap floor ATM curve in combination with the surface. Nodes that have no effect for this parameterisation but that are allowed by the schema are not referenced. The meaning of each of the nodes is as follows:

\begin{itemize}
\item
\lstinline!CurveId!: Unique identifier for the cap floor volatility structure.

\item \lstinline!CurveDescription! [Optional]:
A description of the volatility structure. It is for information only and may be left blank.

\item \lstinline!VolatilityType!:
Indicates the cap floor volatility type. It may be \lstinline!Normal!, \lstinline!Lognormal! or \lstinline!ShiftedLognormal!. Note that this then determines which market data points are looked up in the market when creating the cap floor surface and how they are interpreted when stripping the optionlets. In particular, the market will be searched for market data points of the form \lstinline!CAPFLOOR/RATE_NVOL/Currency/Tenor/IndexTenor/0/0/Strike!, \lstinline!CAPFLOOR/RATE_LNVOL/Currency/Tenor/IndexTenor/0/0/Strike! or \lstinline!CAPFLOOR/RATE_SLNVOL/Currency/Tenor/IndexTenor/0/0/Strike! respectively.

\item \lstinline!Extrapolation!:
Indicates the extrapolation in the time and strike direction. The extrapolation occurs on the stripped optionlet volatilities. The allowable values are \lstinline!None!, \lstinline!Flat! and \lstinline!Linear!. If set to \lstinline!None!, extrapolation is turned off and an exception is thrown if the optionlet surface is queried outside the allowable times or strikes. If set to \lstinline!Flat!, the optionlet volatility on the time strike boundary is used if the optionlet surface is queried outside the allowable times or strikes. If set to \lstinline!Linear!, the interpolation method configured in \lstinline!InterpolationMethod! is used to extrapolate either time or strike direction.

\item \lstinline!InterpolationMethod! [Optional]:
Indicates the interpolation in the time and strike direction. As \lstinline!InterpolateOn! is set to \lstinline!TermVolatilities! here, the interpolation is used in the stripping process to interpolate the term cap floor volatility surface as explained above. It is also used to interpolate the optionlet volatilities when an optionlet volatility is queried from the stripped optionlet structure. The allowable values are \lstinline!Bilinear! and \lstinline!BicubicSpline!. If not set, \lstinline!BicubicSpline! is assumed.

\item \lstinline!IncludeAtm!:
A boolean value indicating if an ATM curve should be used in combination with the surface. Allowable boolean values are given in the Table \ref{tab:boolean_allowable}. If set to \lstinline!true!, the \lstinline!AtmTenors! node needs to be populated with the ATM tenors to use. The ATM quotes that are searched for are as outlined in the previous two ATM sections above. The original stripped optionlet surface is amended by inserting the optionlet volatilities at the successive ATM strikes that reproduce the sequence of ATM cap volatilities.

\item \lstinline!DayCounter!:
The day counter used to convert from dates to times in the underlying structure. Allowable values are given in the Table \ref{tab:daycount}.

\item \lstinline!Calendar!:
The calendar used to advance dates by periods in the underlying structure. In particular, it is used in deriving the cap maturity dates from the configured cap tenors. Allowable values are given in the Table \ref{tab:calendar}.

\item \lstinline!BusinessDayConvention!:
The business day convention used to advance dates by periods in the underlying structure. In particular, it is used in deriving the cap maturity dates from the configured cap tenors. Allowable values are given in the Table \ref{tab:allow_stand_data} under \lstinline!Roll Convention!.

\item \lstinline!Tenors!:
A comma separated list of valid tenor strings giving the cap floor maturity tenors to be used in the tenor by strike surface. In this case, i.e.\ configuring a surface, they must be provided.

\item \lstinline!IborIndex!:
A valid interest rate index name giving the index underlying the cap floor quotes. Allowable values are given in the Table \ref{tab:indices}.

\item \lstinline!DiscountCurve!:
A reference to a valid discount curve specification that will be used to discount cashflows during the stripping process. It should be of the form \lstinline!Yield/Currency/curve_name! where \lstinline!curve_name! is the name of a yield curve defined in the yield curve configurations.

\item \lstinline!AtmTenors! [Optional]:
A comma separated list of valid tenor strings giving the cap floor maturity tenors to be used in the ATM curve. It must be provided when \lstinline!IncludeAtm! is \lstinline!true! and omitted when \lstinline!IncludeAtm! is \lstinline!false!.

\item \lstinline!SettlementDays! [Optional]:
Any non-negative integer is allowed here. If omitted, it is assumed to be 0. If provided the reference date of the term volatility curve and the stripped optionlet volatility structure will be calculated by advancing the valuation date by this number of days using the configured calendar and business day convention. In general, this should be omitted or set to 0.

\item \lstinline!InterpolateOn!:
As referenced above, the allowable values are \lstinline!TermVolatilities! or \lstinline!OptionletVolatilities!. As we are describing here a surface with interpolation on term volatilities, this should be set to \lstinline!TermVolatilities! as shown in Listing \ref{lst:capfloorvol_surface_configuration_term}.

\item \lstinline!BootstrapConfig! [Optional]:
This node holds configuration details for the iterative bootstrap that are described in section \ref{sec:bootstrap_config}. If omitted, this node's default values described in section \ref{sec:bootstrap_config} are used.

\end{itemize}

\begin{longlisting}
\begin{minted}[fontsize=\footnotesize]{xml}
<CapFloorVolatility>
  <CurveId>...</CurveId>
  <CurveDescription>...</CurveDescription>
  <VolatilityType>...</VolatilityType>
  <Extrapolation>...</Extrapolation>
  <InterpolationMethod>...</InterpolationMethod>
  <IncludeAtm>...</IncludeAtm>
  <DayCounter>...</DayCounter>
  <Calendar>...</Calendar>
  <BusinessDayConvention>...</BusinessDayConvention>
  <Tenors>...</Tenors>
  <IborIndex>...</IborIndex>
  <DiscountCurve>...</DiscountCurve>
  <AtmTenors>...</AtmTenors>
  <SettlementDays>...</SettlementDays>
  <InterpolateOn>TermVolatilities</InterpolateOn>
  <BootstrapConfig>...</BootstrapConfig>
</CapFloorVolatility>
\end{minted}
\caption{Cap floor surface with interpolation on term volatilities.}
\label{lst:capfloorvol_surface_configuration_term}
\end{longlisting}

Listing \ref{lst:capfloorvol_surface_configuration_opt} shows the layout for parameterising a cap tenor by absolute cap strike volatility surface with interpolation on optionlet volatilities. This parameterisation also allows for the inclusion of a cap floor ATM curve in combination with the surface. Nodes that have no effect for this parameterisation but that are allowed by the schema are not referenced. The meaning of each of the nodes is as follows:

\begin{itemize}
\item
\lstinline!CurveId!: Unique identifier for the cap floor volatility structure.

\item \lstinline!CurveDescription! [Optional]:
A description of the volatility structure. It is for information only and may be left blank.

\item \lstinline!VolatilityType!:
Indicates the cap floor volatility type. It may be \lstinline!Normal!, \lstinline!Lognormal! or \lstinline!ShiftedLognormal!. Note that this then determines which market data points are looked up in the market when creating the cap floor surface and how they are interpreted when stripping the optionlets. In particular, the market will be searched for market data points of the form \lstinline!CAPFLOOR/RATE_NVOL/Currency/Tenor/IndexTenor/0/0/Strike!, \lstinline!CAPFLOOR/RATE_LNVOL/Currency/Tenor/IndexTenor/0/0/Strike! or \lstinline!CAPFLOOR/RATE_SLNVOL/Currency/Tenor/IndexTenor/0/0/Strike! respectively.

\item \lstinline!Extrapolation!:
The allowable values are \lstinline!None!, \lstinline!Flat! and \lstinline!Linear!. If set to \lstinline!None!, extrapolation is turned off and an exception is thrown if the optionlet surface is queried outside the allowable times or strikes. Otherwise, extrapolation is allowed and the type of extrapolation is determined by the \lstinline!TimeInterpolation! and \lstinline!StrikeInterpolation! node values described below.

\item \lstinline!IncludeAtm!:
A boolean value indicating if an ATM curve should be used in combination with the surface. Allowable boolean values are given in the Table \ref{tab:boolean_allowable}. If set to \lstinline!true!, the \lstinline!AtmTenors! node needs to be populated with the ATM tenors to use. The ATM quotes that are searched for are as outlined in the previous two ATM sections above. The original stripped optionlet surface is amended by inserting the optionlet volatilities at the configured ATM strikes that reproduce the configured ATM cap volatilities.

\item \lstinline!DayCounter!:
The day counter used to convert from dates to times in the underlying structure. Allowable values are given in the Table \ref{tab:daycount}.

\item \lstinline!Calendar!:
The calendar used to advance dates by periods in the underlying structure. In particular, it is used in deriving the cap maturity dates from the configured cap tenors. Allowable values are given in the Table \ref{tab:calendar}.

\item \lstinline!BusinessDayConvention!:
The business day convention used to advance dates by periods in the underlying structure. In particular, it is used in deriving the cap maturity dates from the configured cap tenors. Allowable values are given in the Table \ref{tab:allow_stand_data} under \lstinline!Roll Convention!.

\item \lstinline!Tenors!:
A comma separated list of valid tenor strings giving the cap floor maturity tenors to be used in the tenor by strike surface. In this case, i.e.\ configuring a surface, they must be provided.

\item \lstinline!IborIndex!:
A valid interest rate index name giving the index underlying the cap floor quotes. Allowable values are given in the Table \ref{tab:indices}.

\item \lstinline!DiscountCurve!:
A reference to a valid discount curve specification that will be used to discount cashflows during the stripping process. It should be of the form \lstinline!Yield/Currency/curve_name! where \lstinline!curve_name! is the name of a yield curve defined in the yield curve configurations.

\item \lstinline!AtmTenors! [Optional]:
A comma separated list of valid tenor strings giving the cap floor maturity tenors to be used in the ATM curve. It must be provided when \lstinline!IncludeAtm! is \lstinline!true! and omitted when \lstinline!IncludeAtm! is \lstinline!false!.

\item \lstinline!SettlementDays! [Optional]:
Any non-negative integer is allowed here. If omitted, it is assumed to be 0. If provided the reference date of the term volatility curve and the stripped optionlet volatility structure will be calculated by advancing the valuation date by this number of days using the configured calendar and business day convention. In general, this should be omitted or set to 0.

\item \lstinline!InterpolateOn!:
As referenced above, the allowable values are \lstinline!TermVolatilities! or \lstinline!OptionletVolatilities!. As we are describing here a surface with interpolation on optionlet volatilities, this should be set to \lstinline!OptionletVolatilities! as shown in Listing \ref{lst:capfloorvol_surface_configuration_opt}.

\item \lstinline!TimeInterpolation!:
Indicates the interpolation and extrapolation, if allowed by the \lstinline!Extrapolation! node, in the time direction. As \lstinline!InterpolateOn! is set to \lstinline!OptionletVolatilities! here, the interpolation is used to interpolate the optionlet volatilities only i.e.\ there is no interpolation on the term cap floor volatility curve. The allowable values are \lstinline!Linear!, \lstinline!LinearFlat!, \lstinline!BackwardFlat!, \lstinline!Cubic! and \lstinline!CubicFlat!. If not set, \lstinline!LinearFlat! is assumed. Note that \lstinline!Linear! indicates linear interpolation and linear extrapolation. \lstinline!LinearFlat! indicates linear interpolation and flat extrapolation. Analogous meanings apply for \lstinline!Cubic! and \lstinline!CubicFlat!.

\item \lstinline!StrikeInterpolation!:
Indicates the interpolation and extrapolation, if allowed by the \lstinline!Extrapolation! node, in the strike direction. Again, as \lstinline!InterpolateOn! is set to \lstinline!OptionletVolatilities! here, the interpolation is used to interpolate the optionlet volatilities in the strike direction. The allowable values are \lstinline!Linear!, \lstinline!LinearFlat!, \lstinline!Cubic! and \lstinline!CubicFlat!. If not set, \lstinline!LinearFlat! is assumed.

\item \lstinline!BootstrapConfig! [Optional]:
This node holds configuration details for the iterative bootstrap that are described in section \ref{sec:bootstrap_config}. If omitted, this node's default values described in section \ref{sec:bootstrap_config} are used.

\end{itemize}

\begin{longlisting}
\begin{minted}[fontsize=\footnotesize]{xml}
<CapFloorVolatility>
  <CurveId>...</CurveId>
  <CurveDescription>...</CurveDescription>
  <VolatilityType>...</VolatilityType>
  <Extrapolation>...</Extrapolation>
  <InterpolationMethod>...</InterpolationMethod>
  <IncludeAtm>...</IncludeAtm>
  <DayCounter>...</DayCounter>
  <Calendar>...</Calendar>
  <BusinessDayConvention>...</BusinessDayConvention>
  <Tenors>...</Tenors>
  <IborIndex>...</IborIndex>
  <DiscountCurve>...</DiscountCurve>
  <AtmTenors>...</AtmTenors>
  <SettlementDays>...</SettlementDays>
  <InterpolateOn>OptionletVolatilities</InterpolateOn>
  <TimeInterpolation>...</TimeInterpolation>
  <StrikeInterpolation>...</StrikeInterpolation>
  <BootstrapConfig>...</BootstrapConfig>
</CapFloorVolatility>
\end{minted}
\caption{Cap floor surface with interpolation on optionlet volatilities.}
\label{lst:capfloorvol_surface_configuration_opt}
\end{longlisting}