\section{List of Variables}
Are you ever confused about what something is? Do you ever forget what a variable represents? Then I got the solution for you. The following overview will explain what each variable is and
represents. I will try to not use one variable for the same thing, though that is sometimes very difficult to do. I'll do my best. In the meantime, enjoy this exstensive list. Note that this
only applies to variables in code, every symbol in equations are explained at the equations themselves.

\begin{itemize}
    \item $R$: The Gas Constant with value $8.3144621$ ($J(mol)^{-1}K$).
    \item $day$: Length of one day in seconds ($s$).
    \item $year$: Length of one year in seconds ($s$).
    \item $\delta t$: How much time is between each calculation run in seconds ($s$).
    \item $g:$ Magnitude of gravity on the planet in $ms^{-2}$.
    \item $\alpha$: By how many degrees the planet is tilted with respect to the star's plane, also called axial tilt.
    \item $top$: How high the top of the atmosphere is with respect to the planet surface in meters ($m$).
    \item $ins$: Amount of energy from the star that reaches the planet per unit area ($Jm^{-2}$).
    \item $\epsilon$: Absorbtivity of the atmosphere, fraction of how much of the total energy is absorbed (unitless).
    \item $resolution$: The amount of degrees on the latitude longitude grid that each cell has, with this setting each cell is 3 degrees latitude high and 3 degrees longitude wide.
    \item $nlevels \leftarrow 10$: The amount of layers in the atmosphere.
    \item $\delta t_s$: The time between calculation rounds during the spin up period in seconds ($s$).
    \item $t_s$: How long we let the planet spin up in seconds ($s$).
    \item $adv$: Whether we want to enable advection or not.
    \item $velocity$: Whether we want to calculate the air velocity or not.
    \item $adv\_boun$: How many cells away from the poles where we want to stop calculating the effects of advection.
    \item $nlon$: The amount of longitude gridpoints that we use, which depends on the resolution.
    \item $nlat$: The amount of latitude gridpoints that we use, which depends on the resolution.
    \item $T_p$: The temperature of the planet, a 2D array representing a latitude, longitude grid cell.
    \item $T_a$: The temperature of the atmosphere, a 3D array representing a grid cell on the latitude, longitude, atmospheric layer grid.
    \item $\sigma$: The Stefan-Boltzmann constant equal to $5.670373 \cdot 10^{-8} \ (Wm^{-2}K^{-4})$.
    \item $C_a$: Specific heat capacity of the air, equal to $1.0035 Jg^{-1}K^{-1}$.
    \item $C_p$: Specific heat capacity of the planet, equal to $1.0 \cdot 10^{6} Jg^{-1}K^{-1}$.
    \item $a$: Albedo, the reflectiveness of a substance. Note that $a$ is used in general functions as an array that is supplied as input. If that is the case it can be read at the top of the
                algorithm.
    \item $\rho$: The density of the atmosphere, a 3D array representing a grid cell on the latitude, longitude, atmospheric layer grid.
    \item $\delta x$: How far apart the gridpoints are in the $x$ direction in degrees longitude.
    \item $\delta y$: How far apart the gridpoints are in the $y$ direction in degrees latitude.
    \item $\delta z$: How far apart the gridpoints are in the $z$ direction in $m$.
    \item $heights$: How high an atmospheric layer is in $m$.
    \item $\tau$: The optical depth for an atmospheric layer.
    \item $\tau_0$: The optical depth at the planet surface.
    \item $f_l$: The optical depth parameter.
    \item $pressureProfile$: The average pressure taken over all atmospheric layers in a latitude, longitude gridcell.
    \item $densityProfile$:The average density taken over all atmospheric layers in a latitude, longitude gridcell.
    \item $temperatureProfile$: The average temperature taken over all atmospheric layers in a latitude, longitude gridcell.
    \item $U$: Upward flux of radiation, 1D array representing an atmospheric layer.
    \item $D$: Downward flux of radiation, 1D array representing an atmospheric layer.
    \item $u$: The east to west air velocity in $ms^{-1}$.
    \item $v$: The north to south air velocity in $ms^{-1}$.
    \item $w$: The bottom to top air velocity in $ms^{-1}$.
    \item $f$: The coriolis parameter.
    \item $\Omega$: The rotation rate of the planet in $rads^{-1}$.
    \item $p$: The pressure of a latitude, longitude, atmospheric layer gridcell.
    \item $p_0$: The pressure of a latitude, longitude, atmospheric layer gridcell from the previous calculation round.
    \item $\alpha_a$: The thermal diffusivity constant for air.
    \item $\alpha_p$: The thermal diffusivity constant for the planet surface.
    \item $smooth_t$: The smoothing parameter for the temperature.
    \item $smooth_u$: The smoothing parameter for the $u$ component of the velocity.
    \item $smooth_v$: The smoothing parameter for the $v$ component of the velocity.
    \item $smooth_w$: The smoothing parameter for the $w$ component of the velocity.
    \item $smooth_{vert}$: The smoothing parameter for the vertical part of the velocities.
\end{itemize}


% !TeX root = vampy.tex
%vampy-notes.tex
% notes for development of VAMPy (image analysis part of VAMP project)
% all figures concerning Phase Contrast images are based on image file
% pshchelo\images\pipettes\PhC\me\micropipettes6\ves_-000100.tif = phc-test1.tif

\section{Development Notes}
\subsection{Extraction of data from images}\label{data}

For now everything is done in Python with different additional packages.

The pseudocode-like draft for the algorithm for processing single image looks like this:
\begin{enumerate}
  \item load picture to array
  \item get user input
  \item calculate positions of pipette walls
  \item calculate pipette radius
  \item calculate the axis of the system
  \item extract data along the axis from the picture
  \item find positions of 3 characteristic points on the axis
  \item calculate all derived parameters (vesicle radius, tip length, surface area, volume)
  \item calculate dilations and tensions and fit them with some defined function
\end{enumerate}

Python packages aside from Python Standard Library used or (probably) going to be used in this program:
\begin{itemize}
	\item \emph{numpy} --- basic package for numeric stuff, defines \emph{array} data type
	\item \emph{scipy} --- depends on \emph{numpy} and provides a lot of mathematical functions, which I most probably will need \cite{scipy}
	\item \emph{wxPython} --- GUI programming
	\item \emph{psyco} --- JIT compiler for Python, may use it to speed up the execution
	\item \emph{Python Image Library (PIL)} --- basic image processing functionality, but may eventually drop it (see Section \ref{loadpic})
	\item \emph{matplotlib} --- for plotting results
\end{itemize}

\subsubsection{Load picture to array}\label{loadpic}

This is done with \emph{scipy} and \emph{PIL}, which allows for direct conversion from image file to \emph{numpy} array.

On the other hand, \emph{wxPython}'s wxImage object could be probably used, thus eliminating the need of \emph{PIL} package, since I'm going to use \emph{wxPython} for GUI programming anyway. Unfortunately, wxImage still doesn't support \emph{numpy}-like array interface as of now, but this is planned feature for addition. Or buffers interface seems to be able to do this \ldots

\subsubsection{Get user input}\label{getinput}

\begin{figure}
	\includegraphics[width=\columnwidth]{figs/userinput.pdf}
	\caption{User supplied parameters visualized on the aspirated vesicle image. Left blue line is $x_{a0}$, right blue line is $x_{v0}$, green region is approximate pipette tip position, yellow lines define the approximate pipette walls positions, yellow dashed line is approximate pipette axis.}
	\label{fig:userinput}
\end{figure}

First of all user should crop the image so that everything but the vesicle is left out and rotate the picture so that the pipette \emph{sticks from left}. Let us assume the size of the image along the x-axis is now $N$. User supplies several sets of coordinates to define approximate regions of features locations (see Figure \ref{fig:userinput}):
\begin{itemize}
	\item overestimated position of the aspirated vesicle part $x_{a0}$ so that the tip of the aspirated vesicle part must be always to the left from this, $ x_a \in (0, x_{a0})$;
	\item overestimated position of the outer part of the vesicle $x_{v0}$ so that the tip of the outer part of the vesicle is always to the right of it, $ x_v \in (x_{v0}, N)$;
	\item approximate position of the pipette tip, $x_{p1}, x_{p2}$ so that the pipette tip is always in this region, $ x_p \in (x_{p1}, x_{p2})$;
	\item approximate positions of pipette walls.
\end{itemize}

\subsubsection{Define pipette walls}\label{pipwalls}
A cross-sections of the pipette are taken in two points $x=0$ and $x=x_{a0}$. The pipette walls are then taken as global minima in the regions corresponding to the approximate pipette walls positions for each cross-section (see Figure \ref{fig:pipcrosssection}), producing sets of coordinates $(x_1,y_1), (x_2,y_2)$ and $(x_3,y_3), (x_4,y_4)$. The $y$-positions can be further defined more accurately with subpixel resolution (see Section~\ref{subpix}).

\begin{figure}%
	\includegraphics[width=\columnwidth]{figs/pipcrosssection.pdf}%
	\caption{Brightness profile of the pipette cross-section at $x=x_{a0}$. Green regions correspond to user-supplied approximate pipette wall positions, red vertical lines denote the actual found positions of pipette walls.}%
	\label{fig:pipcrosssection}%
\end{figure}

\subsubsection{Calculate pipette radius}\label{calcpiprad}

Distance (unsigned) from point $\left(x_0,y_0\right)$ to line $y=kx+b$ is given by:
\begin{equation}
	\delta = \left|\frac{kx_0+b-y_0}{\sqrt{k^2-1}}\right|\;.
	\label{eq:pointtoline}
\end{equation}
Thus the diameter of the pipette for single image is calculated as mean of distances from every of 4 points to the line corresponding to the opposing wall. Then these values are again averaged between all images.

\subsubsection{Calculate the middle line (axis) of the system}\label{calcaxis}

\begin{figure}
	\includegraphics[width=\columnwidth]{figs/pipetteaxis.pdf}
 	\caption{Sketch of general situation of pipette system alignment on the image}
 	\label{fig:pipetteaxis}
\end{figure}

Having obtained the set of reference points from Section~\ref{pipwalls} one builds a system axis as a bisector between straight lines formed by pipette inner walls. This is done by simply defying the line going through 2 middle points $\left(\frac{x_1+x_2}{2}, \frac{y_1+y_2}{2}\right)$ and $\left(\frac{x_3+x_4}{2}, \frac{y_3+y_4}{2}\right)$. Then the axis $y = kx+b$ is defined by coefficients

\begin{equation}
k = \frac{y_1+y_1-y_3-y_4}{x_1+x_2-x_3-x_4}, \; b = \frac{y_1+y_2}{2} - k\frac{x_1+x_2}{2}\;\;.
\label{eq:axis}
\end{equation}

After that the brightness profile along this axis is extracted from image with special function \texttt{scipy.ndimage.map-coordinates}, which returns spline-interpolated values of brightness ``between'' pixels. To define the set of points at which interpolated brightness should be evaluated first intersections of the system axis with boundaries of image are calculated. To define the number of points for evaluation the biggest of differences in $x$ or $y$ coordinates between intersection points is taken.

Small pitfall --- since at the end we need real distances between features, an attention have to be paid to keep the scale of profiles equal. The above procedure does not keep the scale, because the line has only as many points as there are along one of it's coordinates, but it should be $\sqrt{x^2+y^2}$. Hence, the distance between 2 consecutive points on brightness profile along arbitrary tilted straight line with number of evaluated points as defined above corresponds to distance $\epsilon$ in pixels, where
\begin{equation}
\epsilon = \left\{
\begin{array}{ll}
	\sqrt{1+k^2},&\text{if }k < 1\\
	\sqrt{1+\frac{1}{k^2}},&\text{if } k \geq 1
\end{array}
\right.\;\;,
\label{eq:profilescale}
\end{equation}
so that $1 \leq \epsilon \leq \sqrt{2}$. Thus the procedure of extracting brightness profile must also return the $\epsilon$ value along with profile itself to use it in final steps of determining distances. This is not necessary for profiles used for location of pipette walls, since by design only untilted profiles along pixel lines are used there, thus the scale in preserved.

\subsubsection{Find positions of 3 characteristic points on the axis}\label{points}

We are interested in 3 points on the axis of the system --- intersection of axis with outer vesicle, aspirated tip of a vesicle and the tip of the pipette. These manifest themselves as peaks (positive or negative) or steep jumps on the brightness profile along the axis. What exactly feature corresponds to what point of interest depends on the type of images one analyses.

\begin{itemize}
	\item \textbf{Phase contrast images} \label{phcfeatures}

		\begin{figure}
		\includegraphics[width=\columnwidth]{figs/phcaxisprofile.pdf}%
		\caption{Brightness profile along the system axis for phase contrast image at Figure \ref{fig:pipetteaxis}. Green region corresponds to the user-supplied approximate pipette tip position. Red line denotes actual pipette tip position found. Other features are also clearly distinguishable.}%
		\label{fig:phcaxisprofile}%
		\end{figure}

		For phase contrast images (see Figure \ref{fig:phcaxisprofile}), the pipette tip ought to be a local minima or (in case of too small pipette and/or too bright illumination) a global maxima. Vesicle sides in turn are featured as steep jumps from dark to bright (so the inflection point is a choice for a feature position).

		The pipette tip is first roughly located as the global maximum or minimum in the pipette tip search region, giving the position of the pipette tip with \emph{pixel resolution}. To get a \emph{subpixel resolution} of peak position its vicinity is fitted with some suitable profile (see Section \ref{subpix}) with parameters of the fit giving the value desired.

		As for inflection points, the rough positions are found by first applying a smoothing filter to the brightness profile, taking absolute value of smoothed profile's derivative (Savitzky-Golay \cite{Savitzky1964, Steinier1972} and Gauss smoothing/derivative filters are implemented for now) and than using user input for overestimated feature positions (see Section~\ref{getinput}) to define left and right search regions where global maxima for these regions are found, giving positions of steep jumps with \emph{pixel resolution} - see Figure \ref{fig:phcprofilegrad}. For \emph{subpixel resolution} the profile in the vicinity of estimated position must be fitted with suitable function with well-defined inflection point (see Section~\ref{subpix}).

		\begin{figure}%
		\includegraphics[width=\columnwidth]{figs/phcprofilegrad.pdf}%
		\caption{Result of applying gradient magnitude filter to gaussian-presmoothed profile from Figure \ref{fig:phcaxisprofile}. Red lines correspond to located features positions.}%
		\label{fig:phcprofilegrad}%
		\end{figure}

	\item \textbf{DIC images} \label{dicfeatures}

		For DIC images the aspirated tip is local minimum and the outer edge is local maximum in their respective search regions (or vice versa, depending on choice of polarizations) and pipette tip is (as with phase contrast images) either a local minimum or global maximum in the pipette tip search region. The fitting procedure by itself is the same as for peaks in~Section~\ref{phcfeatures}.

	\item \textbf{Subpixel resolution} \label{subpix}

		\emph{NOT YET IMPLEMENTED}

		Positions of features with subpixel resolutions can be found by making a non-linear least squares fit (\texttt{scipy.optimize.leastsq}, Levenberg-Marquardt implementation) of brightness profile in the vicinity of the pixel-resolved location of the feature using some suitable function. According to \cite{Bitler1999} brightness jumps on the edge of an object observed with phase contrast microscopy are described by integral sine function, with inflection point being the exact position of the object's edge. As for the peaks, for them the Gaussian bell function can be used with position of its maximum defining feature position with subpixel resolution.

\end{itemize}

\subsubsection{Calculation of derived parameters}\label{results}

\begin{figure}%
\includegraphics[width=\columnwidth]{figs/pipettesketch.pdf}%
\caption{Sketch of a vesicle aspirated into the pipette with explanation of parameters.\newline1: $l_a = 2R-l_v$.\newline2: $l_a = r$}%
\label{fig:pipettesketch}%
\end{figure}

Given positions of outer vesicle edge as $x_v$, pipette tip $x_p$ and aspirated vesicle tip $x_t$ plus the pipette radius $r$ together with their corresponding errors $\delta x_v$, $\delta x_p$, $\delta x_t$ and $\delta r$ and assuming total cylindrical symmetry of the system along the system axis and spherical form of the vesicle outside the pipette one can calculate the desired parameters (see Figure \ref{fig:pipettesketch}).

Denoting length of the vesicle part outside the pipette as $l_v = \left|x_p-x_v\right|$ with error $\delta l_v = \delta x_p + \delta x_v$ and the length of the aspirated tip as $l_a = \left|x_p-x_t\right|$ with error $\delta l_a = \delta x_p + \delta x_t$, the radius of the outside vesicle is
\begin{equation*}
R = \frac{{l_v}^2 + r^2}{2l_v}\;\;.
\end{equation*}
Corresponding error is then
\begin{equation*}
 \delta R = \sqrt{\frac{r^2}{{l_v}^2} \left(\delta r\right)^2 + \frac{1}{4}\left(1-\frac{r^2}{{l_v}^2}\right)^2 \left( \delta l_v\right) ^2}\;\;.
\end{equation*}
The surface of the inner part is
\begin{equation*}
S_\text{in} = \left\{
\begin{array}{ll}
	2\pi rl_a,& \text{if } l_a \geq r\\
	\pi\left({l_a}^2+r^2\right),&\text{if } 2R-l_v \leq l_a < r
\end{array}
\right.\;\;,
\end{equation*}
and its volume is
\begin{equation*}
V_{\text{in}} = \left\{
\begin{array}{ll}
	\pi r^2\left(l_a-\frac{r}{3}\right), & \text{if } l_a \geq r\\
	\frac{1}{6}\pi l_a\left(3r^2+{l_a}^2\right),&\text{if } 2R-l_v \leq l_a < r
\end{array}
\right.\;\;,
\end{equation*}
with errors
\begin{equation*}
 \delta S_\text{in} = \left\{
 \begin{array}{ll}
	2\pi \sqrt{{l_a}^2\left(\delta r\right)^2 + r^2\left(\delta l_a\right)^2},& \text{if } l_a \geq r\\
	2\pi \sqrt{{l_a}^2\left(\delta l_a\right)^2 + r^2\left(\delta r\right)^2},&\text{if } 2R-l_v \leq l_a < r
\end{array}
\right.\;\;
\end{equation*}
and
\begin{equation*}
\delta V_{\text{in}} = \left\{
\begin{array}{ll}
	\pi r \sqrt{r^2\left(\delta l_a\right)^2 + \left(2l_a-r\right)^2 \left(\delta r\right)^2}, & \text{if } l_a \geq r\\
	\frac{\pi}{2} \sqrt{4 r^2 {l_a}^2\left(\delta r\right)^2 + \left(r^2+{l_a}^2\right)^2 \left(\delta l_a\right)^2}, & \text{if } 2R-l_v \leq l_a < r
\end{array}
\right.\;\;.
\end{equation*}
The surface of the outer vesicle part is
\begin{equation*}
S_\text{out} = 2\pi Rl_v = \pi \left({l_v}^2+r^2\right)\;\;,
\end{equation*}
and it's volume is
\begin{equation*}
V_\text{out} = \frac{1}{6}\pi l_v\left(3r^2+{l_v}^2\right)\;\;
\end{equation*}
with errors
\begin{equation*}
\delta S_\text{out} = 2\pi\sqrt{{l_v}^2 \left(\delta l_v\right)^2 + r^2 \left( \delta r\right) ^2}\;\;
\end{equation*}
and
\begin{equation*}
\delta V_\text{out} = \frac{\pi}{2} \sqrt{4 r^2 {l_v}^2\left(\delta r\right)^2 + \left(r^2+{l_v}^2\right)^2 \left(\delta l_v\right)^2}\;\;.
\end{equation*}
Total area and volume of the vesicle are then $S = S_\text{out}+S_\text{in}$ and $V = V_\text{out}+V_\text{in}$ with errors $\delta S = \delta S_\text{out} + \delta S_\text{in}$ and $\delta V = \delta V_\text{out} + \delta V_\text{in}$ respectively.

\subsection{Data Analysis}\label{analysis}
\subsubsection{Classical procedure}
Having combined data acquired from image analysis together with corresponding pressure values obtained in experiment one finds elastic properties of membrane by fitting low-tension regime with logarithm and high-tension regime with linear functions. Also some corrections pointed out in \cite{Henriksen2004, Fournier2001} could be accounted for here, by trying to fit the whole range of pressures with one general function.

Currently tensions are calculated according to simple model after Evans:
\begin{equation}
\tau = \frac{P R_p}{2\left(1-\frac{R_p}{R_v}\right)}
\label{eq:tau-evans}
\end{equation}

Below is the list of currently implemented models/fittings.

Dilations:
\begin{itemize}
	\item simplest model $\alpha = \frac{S-S_0}{S_0}$
	\item corrected for initial aspiration after \cite{Henriksen2004}
	\begin{equation}
		\alpha = \left[
		 \frac{1}{2} \left(\frac{R_p}{R_{v0}}\right)^2 \frac{\Delta L}{R_p}
		 + \left[1-\frac{3}{4}\left(\frac{R_p}{R_{v0}}\right)^3 \frac{\Delta L}{R_p} \right]^{\frac{2}{3}}
		 - 1
		\right]\gamma
		\label{eq:alpha-henriksen}
	\end{equation}
	where $\displaystyle{\gamma = 1-\frac{2R_p L_0+R_p^2}{4R_{v0}^2}}$.
	\item approximated correction for initial aspiration after \cite{Henriksen2004} (made for testing)
	\begin{equation}
		\alpha = \frac{1}{2}\left[
		\left(\frac{R_p}{R_{v0}}\right)^2-\left(\frac{Rp}{R_{v0}}\right)^3\right]
		\frac{\Delta L}{R_p}\gamma
		\label{eq:alpha-henriksen-simple}
	\end{equation}
	where $\gamma$ as in equation \ref{eq:alpha-henriksen}.
\end{itemize}

Fittings (done with Orthogonal Distance Regression):
\begin{itemize}
	\item Simple model for bending rigidity: $\alpha=\frac{1}{8\pi\kappa}\ln{\frac{\tau}{\tau_0}}$
	\item Simple model for stretching elasticity: $\alpha=\frac{\tau}{K}+\alpha_0$
\end{itemize}

\subsubsection{Modern procedure}
The overall ultimate goal is to implement a MCMC (Markov Chain Monte Carlo) algorithm found in  \cite{Henriksen2004}.


%!TEX root = Lefley - Mesh to voxel transformations for optimised physics-based interactions.tex
\chapter{Introduction}

\section{Motivation}

Physics simulation is one of the key components of a modern game engine. The more accurate the simulation is, the more immersive games built with the engine are likely to be. If the world around the player does not react as expected then it is difficult to become immersed in the game environment.

\section{Problem}

\label{sect:prob}

The most common representation of a solid object in a physical simulation is a rigid polygonal mesh. This format stores the vertices and faces which define the object's surface, with volume information being implicit. This is optimal for operations which require only the surface information, such as rendering, but presents issues if we wish to reason on the object's interior, as we do when fragmenting under physical forces.

It is possible to fragment an object without knowledge of its interior by simply partitioning the space in which the object exists and refining any partitions which have faces in them. However, as no volumetric information about the object is being used, the fracturing is approximate. A further limitation is that most implementations using similar approaches are restricted to convex objects or must first decompose any concave objects into constituent convex meshes~\cite{Muller:2013:RTD:2461912.2461934}.

Overall, while fragmentation from only surface information is efficient and produces reasonable results, the physical accuracy is limited and this project instead proposes a method which uses the object's volumetric information.

\section{Solution}

\label{sect:sol}

Taking an object as a three dimensional scalar field of mass, we simplify the problem of fragmenting it on the applied physical forces. For each point inside the object we determine which fragment that point should belong to based on the object's physical properties.

When only the boundary is stored, determining whether any given point is inside of an object is non trivial. Consider a series of faces defining a 2D object. Then to label any given point as inside the object we need to check that it is `inside' of all of the faces\cite{Ray-tracing}. Furthermore, this only holds for convex shapes, if there exist any concave sections then we could have a point which is `outside' of a face but inside the 2D object. See Figure~\ref{fig:1.1}.

\begin{figure}[b!]
\centerline{\includegraphics[scale=0.4]{point_inside_concave13.pdf}}
\caption{The green area shows all points `inside' line (a). The red areas shows all points `outside' line (a). Point (b) is `outside' line (a) but inside the defined concave shape.}
\label{fig:1.1}
\end{figure}

Calculating for all points, whether they are inside the object before physical interaction can reduce the simulation time complexity discussed above. We also gain a constant time lookup for checking if any given point lies within the object. This process is known as binary solid voxelisation, where a binary voxel is a point in three dimensional space with an assignment based on whether it is inside or outside of a given object\cite{Schwarz:2010:Vox}.

This project proposes a pipeline for simulating physical destruction, focussing on fragmentation, consisting of the following stages.
\begin{enumerate}
\item{Objects are voxelised}
\item{Each voxel is assigned to a fragment algorithmically in such a way as to emulate the physical properties of the object}
\item{A rigid mesh is built for each fragment from its constituent voxels}
\end{enumerate}

For example, if a bullet is fired at a brick wall, both the bullet and wall will be rigid meshes when the bullet is shot. On collision, both the wall and bullet will be voxelised. Assuming the bullet consists of only one voxel, no destruction calculations will be performed on it. Using the force of impact and physical parameters of the wall, it will be calculated which voxels should belong to which fragments. These fragments will then be transformed back into rigid meshes and the correct movement vectors will be applied. This is illustrated in Figure~\ref{fig:1.2}.

\begin{figure}
\centerline{\includegraphics[scale=0.6]{diagram13.pdf}}
\caption{A simple rigid mesh projectile is fired towards another rigid mesh (a). On collision the destructible body is voxelised (b) depending on the force of the projectile and physical parameters of the objects. It is determined which voxels will detach, shown in red. Meshes are reformed around all separate bodies and physical forces are applied (c).}
\label{fig:1.2}
\end{figure}

This process will be referred to as {\emph{Dynamic Volumetric Fragmentation (DVF)}}.

\section{Related Work}

\subsection{Fragmentation}

\label{sect:relfrag}

One existing method for object destruction is a static approach. Fragments are generated for every destructible object when the objects are created and then substituted for the object on collision. This does not allow the result of the collision to be in any way dependant on the forces involved in the collision and so does not produce realistic results.

Matthias M\"{u}ller, Nuttapong Chentanez and Tae-Yong Kim propose a method for the dynamic destruction of objects in real time. The method uses `volume approximate convex decompositions' to fragment objects which are composed of convex pieces using Voronoi decomposition of space\cite{Muller:2013:RTD:2461912.2461934}.

\subsection{Mesh/Voxel Conversion}

Binary voxelisation of polygonal objects is a memory efficient method for defining occupied space and can be achieved in real-time on modern GPUs. Both surface and solid voxelisation methods are presented by Schwarz and Seidel\cite{Schwarz:2010:Vox}. A solid voxelisation algorithm was used as opposed to surface voxelisation as the entire volume of an object is required for the proposed volumetric destruction.

Both marching tetrahedra and surface nets exist as algorithms for constructing 3D surfaces from volumetric data\cite{Tetrahedra}\cite{Gibson:1998:CES:646921.709482}. An existing implementation of marching tetrahedra has been used as part of the remeshing stage of the pipeline as more literature existed concerning the use of this method with Unity3D\cite{Tetrahedra-CPU}.

\subsection{Related Uses}

Nie\ss{}ner et al present a method for real-time collision detection of patch based objects using mesh to voxel transformations \cite{niessner2013collision}. While their work is on collision detection, it does demonstrate that real-time mesh to voxel conversion is viable for use in resolving physics interactions.

Miguel Cepero is developing a procedural voxel engine Voxel Farm\cite{Procedural-World}. His work includes volumetric destruction of objects in a manner similar to this project's aims\cite{Appetite}.


\documentclass[8pt]{article}
\usepackage[a4paper,landscape,margin=1in]{geometry}
\usepackage{cmbright}

\usepackage{amsmath}
\usepackage{nicefrac}
\usepackage{siunitx}

\usepackage{array}
\usepackage{booktabs}
\usepackage{longtable}

\usepackage{xcolor}
\definecolor{urlblue}{HTML}{0000ee}
\usepackage{hyperref}
\hypersetup{%
colorlinks = true,%
urlcolor   = urlblue,%
}

\usepackage{tcolorbox}
\usepackage{varwidth}

\setlength\parindent{0pt}
\renewcommand{\ss}{\textsuperscript}

\pagenumbering{gobble}

\begin{document}
\begin{figure}[!ht]
% MF group logo
\begin{minipage}[b][2.5cm][c]{.72\textwidth}
\href{http://foroozandeh.chem.ox.ac.uk/home}%
{\includegraphics[scale=1.8]{/home/simon/Documents/DPhil/projects/spectral_estimation/NMR-EsPy/venv/lib/python3.9/site-packages/nmrespy/images/mf_logo.png}}
\end{minipage}
% NMR-EsPy logo
\begin{minipage}[b][2.5cm][c]{.27\textwidth}
\href{https://nmr-espy.readthedocs.io/en/1.0.0rc1/}%
{\includegraphics[scale=0.5]{/home/simon/Documents/DPhil/projects/spectral_estimation/NMR-EsPy/venv/lib/python3.9/site-packages/nmrespy/images/nmrespy_full.png}}
\end{minipage}
\end{figure}

\texttt{16:59:22\\28-05-2021}

% user provided description
\subsection*{Description}
50mM cyclosporin in Benzene-d6 (Example 1)

% experiment parameters
\subsection*{Experiment Information}
\hspace{-6pt}
\begin{tabular}{ll}
Sweep Width (Hz) & 5494.51 \\
Sweep Width (ppm) & 10.9861 \\
Transmitter Offset (Hz) & 2249.21 \\
Transmitter Offset (ppm) & 4.49722 \\
Transmitter Frequency (MHz) & 500.132 \\
Basic Frequency (MHz) & 500.13 \\
Nucleus & $^{1}$H \\
Filter region (Hz): & 2644.19 - 2593.21 \\
Filter region (ppm): & 5.28697 - 5.18505 \\

\end{tabular}

\subsection*{Result}
\begin{longtable}[l]{cccccccc}
\toprule
$m$ & $a_m$ & $\phi_m\ (\text{rad})$ & $f_m\ (\text{Hz})$ & $f_m\ (\text{ppm})$ & $\eta_m\ (\text{s}^{-1})$ & $\int$ & $\nicefrac{\int}{\left\lVert\int\right\rVert}$ \\

\midrule
1 & \num{1.5945e4} & 0.029904 & \num{2.6019e3} & 5.2023 & 7.371 & \num{1.4467e9} & 0.274 \\
 & $\pm$ 80.299 & $\pm$ \num{9.0154e-3} & $\pm$ \num{9.4141e-3} & $\pm$ \num{1.8823e-5} & $\pm$ 0.043436 & - & - \\
2 & \num{3.2978e4} & \num{6.343e-3} & \num{2.6093e3} & 5.2172 & 6.7376 & \num{3.023e9} & 0.57253 \\
 & $\pm$ 206.9 & $\pm$ \num{3.5484e-3} & $\pm$ \num{2.1995e-3} & $\pm$ \num{4.3979e-6} & $\pm$ 0.034551 & - & - \\
3 & \num{1.5949e4} & \num{8.2753e-3} & \num{2.6116e3} & 5.2218 & 7.4847 & \num{1.4446e9} & 0.27359 \\
 & $\pm$ 308.45 & $\pm$ 0.012671 & $\pm$ \num{8.2016e-3} & $\pm$ \num{1.6399e-5} & $\pm$ 0.093504 & - & - \\
4 & \num{1.9198e4} & \num{8.7189e-4} & \num{2.6167e3} & 5.2319 & 8.4204 & \num{1.7155e9} & 0.32489 \\
 & $\pm$ 199.66 & $\pm$ \num{9.4538e-3} & $\pm$ 0.011157 & $\pm$ \num{2.2309e-5} & $\pm$ 0.070405 & - & - \\
5 & \num{2.9948e4} & \num{-3.8286e-3} & \num{2.619e3} & 5.2366 & 6.3228 & \num{2.765e9} & 0.52367 \\
 & $\pm$ 205.49 & $\pm$ \num{6.0139e-3} & $\pm$ \num{4.5162e-3} & $\pm$ \num{9.0299e-6} & $\pm$ 0.034655 & - & - \\
6 & 708.57 & \num{3.7992e-3} & \num{2.6219e3} & 5.2424 & 5.6154 & \num{6.6293e7} & 0.012555 \\
 & $\pm$ 122.71 & $\pm$ \num{9.0038e-3} & $\pm$ 0.074974 & $\pm$ \num{1.4991e-4} & $\pm$ 0.82271 & - & - \\
7 & \num{2.1844e4} & \num{-9.6734e-3} & \num{2.6262e3} & 5.2509 & 8.6988 & \num{1.9445e9} & 0.36827 \\
 & $\pm$ 111.5 & $\pm$ \num{5.0574e-3} & $\pm$ \num{6.8436e-3} & $\pm$ \num{1.3684e-5} & $\pm$ 0.050882 & - & - \\
8 & 673.59 & \num{3.4037e-3} & \num{2.6299e3} & 5.2584 & 5.2998 & \num{6.3426e7} & 0.012012 \\
 & $\pm$ 76.526 & $\pm$ \num{5.3405e-3} & $\pm$ 0.068378 & $\pm$ \num{1.3672e-4} & $\pm$ 0.63093 & - & - \\
9 & \num{4.6997e3} & \num{-2.8134e-3} & \num{2.6365e3} & 5.2715 & 7.0852 & \num{4.2836e8} & 0.081127 \\
 & $\pm$ 59.003 & $\pm$ \num{4.1243e-3} & $\pm$ 0.014385 & $\pm$ \num{2.8763e-5} & $\pm$ 0.11783 & - & - \\

\bottomrule
\end{longtable}

% blurb
\small
\begin{tcolorbox}[hbox]
\begin{varwidth}{\textwidth}
Estimation performed using \textsc{NMR-EsPy}.\\
Author: Simon Hulse\\
For more information:\\[5pt]
{\raisebox{-4pt}{\includegraphics[scale=0.029]{/home/simon/Documents/DPhil/projects/spectral_estimation/NMR-EsPy/venv/lib/python3.9/site-packages/nmrespy/images/book_icon.png}}}\hspace{1em}\href{https://nmr-espy.readthedocs.io/en/1.0.0rc1/}{\texttt{https://nmr-espy.readthedocs.io/en/1.0.0rc1/}}\\[5pt]
{\raisebox{-4pt}{\includegraphics[scale=0.12]{/home/simon/Documents/DPhil/projects/spectral_estimation/NMR-EsPy/venv/lib/python3.9/site-packages/nmrespy/images/github.png}}}\hspace{1em}\href{https://github.com/foroozandehgroup/NMR-EsPy}{\texttt{https://github.com/foroozandehgroup/NMR-EsPy}}\\[5pt]
{\raisebox{-3pt}{\includegraphics[scale=0.015]{/home/simon/Documents/DPhil/projects/spectral_estimation/NMR-EsPy/venv/lib/python3.9/site-packages/nmrespy/images/email_icon.png}}}\hspace{1em}\href{mailto:simon.hulse@chem.ox.ac.uk?subject=NMR-EsPy query}{\texttt{simon.hulse@chem.ox.ac.uk}}\\[5pt]
If used in a publication, please cite:\\
\textit{No references yet...}
\end{varwidth}
\end{tcolorbox}

\end{document}


\chapter{POD YAML Configuration}
\label{ch:pod_yaml_configuration}
The YAML configuration file for the POD allows you to specify how the and what data the POD will process and what results and statistics to report at the end.
In order to use the yaml configuration file you will need to specify this at the command line, with the \emph{-y <yaml\_filename>} otherwise it will default to the (no longer supported) traditional \emph{POD.in, EQM.in and VEQ.in} option files.

\begin{lstlisting}[language=bash,caption=calling the yaml configuration file]
$ pod -y example_configuration.yaml
\end{lstlisting}

\section{POD processing options (pod\_options)}
%

These options will control how the pod will process the input files, with four different options available. Only one of the options listed below can be set to true, the remainder must be set to false.\\
\begin{table}[h!]
\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
	\hline
    Option & Values & Comments \\
    \hline
    %\multicolumn{3}{|p{13cm}|}{In this section only one of the following options listed below can be set to true, the remainder must be set to false.}\\
    %\hline
	\textbf{pod\_mode\_fit} & true or false & Orbit Determination (pseudo-observations; orbit fitting \ ) \\
	\textbf{pod\_mode\_predict} & true or false & Orbit Determination and Prediction \\
	\textbf{pod\_mode\_eqm\_int} & true or false & Orbit Integration (Equation of Motion only) \\
	\textbf{pod\_mode\_ic\_int} & true or false & Orbit Integration and Partials (Equation of Motion and Variational Equations) initial condition integration \\
	\hline
\end{tabular}
\caption{POD YAML: processing options}
\label{table:pod_yaml_processing_options}
\end{table}
%
\begin{lstlisting}[language=xml,caption=pod\_options yaml configuration example]
pod_options:
# Example YAML showing different processing options
#--------------------------------------------------
pod_mode_fit:     true
pod_mode_predict: false
pod_mode_eqm_int: false
pod_mode_ic_int:  false
\end{lstlisting}
%
\begin{enumerate}
	\item \textbf{pod\_mode\_fit} - this is used to fit an existing sp3 file (this is sometimes referred to as pseudo observations) with the parameters that are set later on. See pod example 1
	\item \textbf{pod\_mode\_predict} - determine an orbit from observations and then predict the orbits path
	\item \textbf{pod\_mode\_eqm\_int} - determine the equations of motion only
	\item \textbf{pod\_mode\_ic\_int} -set up the initial conditions
\end{enumerate}

\section{Time scale(time\_scale)}
%
\begin{table}[h!]
\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
\hline
Option & Values & Comments \\
\hline
\textbf{TT\_time} & true or false & Terrestrial (TT)\\
\textbf{UTC\_time} & true or false & Universal (UTC)\\
\textbf{GPS\_time} & true or false & Satellite (GPS)\\
\textbf{TAI\_time} & true or false & Atomic (TAI)\\
\hline
\end{tabular}
\caption{POD YAML: Time scale options}
\label{table:pod_yaml_time_scale_options}
\end{table}
%
\begin{lstlisting}[language=xml,caption=time\_scale yaml configuration example]
	time_scale:
		TT_time:  false
		UTC_time: false
		GPS_time: true
		TAI_time: false
\end{lstlisting}
%
\begin{enumerate}
	\item \textbf{TT\_time} -
	\item \textbf{UTC\_time} -
	\item \textbf{GPS\_time} -
	\item \textbf{TAI\_time} -
\end{enumerate}
%
\section{Initial Conditions (IC)}
\subsection{IC input format (ic\_input\_filename)}
 one is true, the other is false. If icf selected the ic\_filename value specifies the path to the file.
\begin{table}[h!]
\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
	\hline
	Option & Values & Comments \\
	\hline
   sp3 & true or false & sp3 format file\\
   icf & true or false & initial conditions file\\
   \hline
\end{tabular}
\caption{POD YAML: Initial Conditions input format options}
\label{table:pod_yaml_ic_format}
\end{table}
%
\begin{lstlisting}[language=xml,caption=ic\_input\_format yaml configuration example]
 	ic_input_format:
		sp3:  true   # Input a-priori orbit in sp3 format
		icf:  false  # Input a-priori orbit in POD Initial Conditions File (ICF) format
		ic_filename: some_file
\end{lstlisting}
%
\subsection{IC input reference system (ic\_input\_refsys)}
reference system for the initial conditions one is true, the other is false.
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{itrf} & true or false & terestrial\\
		\textbf{icrf} & true or false & celestial \\
		\textbf{kepler} & true or false & polar form of celestial\\
		\hline
	\end{tabular}
	\caption{POD YAML: Initial Conditions reference system}
	\label{table:pod_yaml_ic_ref_system}
\end{table}
%
\begin{lstlisting}[language=xml,caption=ic\_input\_refsys yaml configuration example]
   ic_input_refsys:
		itrf: true   # Initial Conditions Reference Frame: ITRF, ICRF
		icrf: false  # Initial Conditions Reference Frame: ITRF, ICRF
		kepler: false
\end{lstlisting}
%
\section{Using Pseudo observartions}
These options are used to control how pseudo observations are used by the POD.

\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{pseudobs\_orbit\_filename} & filename & \emph{path to the observations file}\\
		\textbf{pseudobs\_interp\_step} & int &  Interval (sec) of the interpolated orbit\\
		\textbf{pseudobs\_interp\_points} & int & Number of data points used in Lagrange interpolation (at least 2)\\
		\hline
	\end{tabular}
	\caption{POD YAML: Using pseudo observations}
	\label{table:pod_yaml_pseudo_obs}
\end{table}
%
\begin{lstlisting}[language=xml,caption=pseudo observation model yaml configuration example]
	pseudobs_orbit_filename: igs19424.sp3 # Pseudo observations orbit filename
	pseudobs_interp_step:    900          # Interval (sec) of the interpolated orbit
	pseudobs_interp_points:  12           # Number of data points used in Lagrange interpolation
\end{lstlisting}
%
\section{Orbit arc length}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{orbit\_arc\_determination} & int &\emph{number of hours to integrate}\\
		\textbf{orbit\_arc\_prediction} & int &  \emph{number of hours to predict at end of orbit arc}\\
		\textbf{orbit\_arc\_backwards} & int & \emph{number of hours to check before start of orbit arc}\\
		\hline
	\end{tabular}
	\caption{POD YAML: Orbit arc options}
	\label{table:pod_yaml_orbit_arc}
\end{table}
%
\begin{lstlisting}[language=xml,caption=orbit arc length yaml configuration example]
# Orbit arc length (in hours)
	orbit_arc_determination: 24  # Orbit Estimation arc
	orbit_arc_prediction:    12  # Orbit Prediction arc
	orbit_arc_backwards:     2   # Orbit Propagation backwards arc
\end{lstlisting}
%
\section{External Orbit Comparison}
In this section only one of the following options listed below can be set to true, the remainder must be set to false.\\
\begin{table}[h!]
\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
	\hline
	Option & Values & Comments \\
	\hline
	\textbf{ext\_orbit\_enabled}  & true or false & \\
	\textbf{ext\_orbit\_type\_sp3}  & true or false & \\
	\textbf{ext\_orbit\_type\_interp} & true or false & \\
	\textbf{ext\_orbit\_type\_kepler} & true or false & \\
	\textbf{ext\_orbit\_type\_lagrange} & true or false & \\
	\textbf{ext\_orbit\_type\_position\_sp3} & true or false & \\
	\textbf{ext\_orbit\_filename} & filename &  \emph{path to the orbit file}\\
	\textbf{ext\_orbit\_interp\_step} & int & Interval (sec) of the interpolated\/Kepler orbit\\
	\textbf{ext\_orbit\_interp\_points} & int & Number of data points used in Lagrange interpolation (at least 2)\\
    \hline
\end{tabular}
	\caption{POD YAML: External orbit options}
	\label{table:pod_yaml_external_orbit}
\label{table:yaml}
\end{table}
%
\begin{lstlisting}[language=xml,caption=orbit arc length yaml configuration example]

# External Orbit Comparison
	ext_orbit_enabled: true
	ext_orbit_type_sp3:       false        # Orbit data in sp3 format
	                                       # (including position and velocity vectors)
	ext_orbit_type_interp:    true         # Interpolated orbit based on Lagrange
	                                       # interpolation of sp3 file
	ext_orbit_type_kepler:    false        # Keplerian orbit
	ext_orbit_type_lagrange:  false        # 3-day Lagrange interpolation
	ext_orbit_type_position_sp3:    false  # Position and SP3 file
	ext_orbit_filename:       igs19424.sp3 # External (comparison) orbit filename
	ext_orbit_interp_step:    900          # Interval (sec) of the interpolated/Kepler orbit
	ext_orbit_interp_points:  12           # Number of data points used
	                                       # in Lagrange interpolation
\end{lstlisting}
%
\subsection{External orbit reference frame (ext\_orbit\_frame)}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{itrf}  & true or false & terrestrial\\
		\textbf{icrf}  & true or false & celestial\\
		\textbf{kepler} & true or false & kepler orbital elements\\
        \hline
	\end{tabular}
	\caption{POD YAML: External orbit reference system}
	\label{table:pod_yaml_ext_orbit_ref_system}
\end{table}
%
\begin{lstlisting}[language=xml,caption=external orbit reference frame yaml configuration example]
   ext_orbit_frame:
		itrf: true            # External orbit reference frame - ITRF
		icrf: false           # External orbit reference frame - ICRF
		kepler: false
\end{lstlisting}
%
\section{Earth Orientation Parameters}
In this section only one of the following options listed below can be set to true, the remainder must be set to false.\\
\subsection{EOP type}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{EOP\_soln\_c04} & true or false & C04 is the IERS solution\\
		\textbf{EOP\_soln\_rapid} & true or false & Rapid is the rapid\/prediction center solution\\
		\textbf{EOP\_soln\_igs} & true or false & igs is the ultra-rapid solution using partials. To use this you need both the rapid file and partials file.\\
		\textbf{EOP\_soln\_c04\_file} & filename & \\
		\textbf{EOP\_soln\_rapid\_file} & filename & \\
		\textbf{ERP\_soln\_igs\_file} & filename & \\
		\textbf{EOP\_soln\_interp\_points} & int & \\
		\hline
	\end{tabular}
	\caption{POD YAML: Earth Orientation Parameter solution options}
	\label{table:pod_yaml_eop_sol}
\end{table}
%
\begin{lstlisting}[language=xml,caption=eop estimation options]
   	EOP_soln_c04:   true         # IERS C04 solution : EOP_sol = 1
	EOP_soln_rapid: false        # IERS rapid service/prediction center (RS/PC) Daily : EOP_sol = 2
	EOP_soln_igs:   false        # IGS ultra-rapid ERP + IERS RS/PC Daily (dX,dY) : EOP_sol = 3. Need both rapid_file AND igs_file
	EOP_soln_c04_file: eopc04_14_IAU2000.62-now
	EOP_soln_rapid_file: finals2000A.daily
	ERP_soln_igs_file: igu18543_12.erp
	EOP_soln_interp_points: 4    # EOP solution interpolation points
\end{lstlisting}
%
\subsection{IAU Precession-Nutation model}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
        \textbf{eop\_soln\_interp\_points} & int & number of data points to be used in an eop interpolation (at least 2!)\\
        \textbf{iau\_model\_2000} & true or false & \\
        \textbf{iau\_model\_2006} & true or false & \\
		\hline
	\end{tabular}
	\caption{POD YAML: EOP model options}
	\label{table:pod_yaml_eop_model}
\end{table}
%
	\begin{lstlisting}[language=xml,caption=eop model]
	# IAU Precession-Nutation model:
	iau_model_2000: true         # IAU2000A: iau_pn_model = 2000
	iau_model_2006: false        # IAU2006/2000A: iau_pn_model = 2006
	\end{lstlisting}
%
\section{Input files}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
        \textbf{gravity\_model\_file} & filename & \\
        \textbf{DE\_fname\_header} & filename &  Emphemeris header file \\
        \textbf{DE\_fanme\_data} & filename & Emphemeris data file \\
        \textbf{ocean\_tides\_model\_file} & filename & \\
        \textbf{leapsec\_filename} & filename & leapseconds to be added\\
        \textbf{satsinex\_filename} & filename & sinex file with satellite meta-data\\
		\hline
	\end{tabular}
	\caption{POD YAML: Input files}
	\label{table:pod_yaml_input_files}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for general input files]
# Gravity model file
gravity_model_file: goco05s.gfc
# goco05s.gfc, eigen-6s2.gfc, ITSG-Grace2014k.gfc

# Planetary/Lunar ephemeris - JPL DE Ephemeris
DE_fname_header: header.430_229
DE_fname_data:   ascp1950.430

# Ocean tide model file
ocean_tides_model_file: fes2004_Cnm-Snm.dat
# FES2004 ocean tide model

# Leap second filename
leapsec_filename: leap.second

# Satellite metadata SINEX
satsinex_filename: igs_metadata_2063.snx
\end{lstlisting}
%

\section{Output options}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
        \textbf{sp3\_velocity} & true or false & if you wish to write out the velocities for comparison \\
        \textbf{partials\_velocity}: true or false & if you wish to write velocity vector partials to the output file\\
		\hline
	\end{tabular}
	\caption{POD YAML: Output options}
	\label{table:pod_yaml_output_options}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for output file optionss]
# Write to sp3 orbit format: Option for write Satellite Velocity vector
sp3_velocity: false        #  Write Velocity vector to sp3 orbit

#----------------------------------------------------------------------
# Write partials of the velocity vector w.r.t. parameters into the orbits_partials output file:
partials_velocity: false   # Write out velocity vector partials wrt orbital state vector elements
\end{lstlisting}
%
\section{Variational Equation Options}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{veq\_integration}& true or false &   pod mode overides it anyway. Ignore.\\
		\hline
		\textbf{ITRF} & true or false & reference\_frame\\
		\textbf{ICRF} & true or false &  one must be true\\
		\textbf{kepler} & true or false & \\
		\hline
	\end{tabular}
	\caption{POD YAML: VEQ ref system}
	\label{table:pod_yaml_veq_ref_sys}
\end{table}
%

\begin{lstlisting}[language=xml,caption=yaml example for variational equation options]
# Variational Equations
veq_integration: false

#----------------------------------------------------------------------
# Reference System for Variational Equations'  - Partials & Parameter Estimation
veq_refsys:
itrs: true      # ITRS: Terrestrial Reference System
icrs: false     # ICRS: Celestial Reference System
kepler: false
\end{lstlisting}

\section{General Options}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
        \textbf{estimator\_iterations} & int & integrate this number of times, using the generated initial conditions from the previous run as a start point\\
        \hline
	\end{tabular}
	\caption{POD YAML: general options}
	\label{table:pod_yaml_general_options}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for output file options]
	# Parameter Estimation
	estimator_iterations: 2
\end{lstlisting}
%
\section{Apriori solar radiation models}
%
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{no\_model}  & true or false & \\
		\textbf{cannon\_ball\_model} & true or false & see \nameref{sec:cannonball_srp}\\
		\textbf{simple\_boxwing\_model} & true or false & \\
		\textbf{full\_boxwing\_model} & true or false & \\
		\hline
	\end{tabular}
	\caption{POD YAML: Apriori SRP model}
	\label{table:pod_yaml_apriori_srp}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for apriori srp model options]
srp_apriori_model:
	no_model:   false
	cannon_ball_model:   true
	simple_boxwing_model:   false
	full_boxwing_model:     false
\end{lstlisting}
%
\subsection{Estimated Solar radiation models}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{ECOM1}  & true or false & \\
		\textbf{ECOM2}  & true or false & \\
		\textbf{hybrid} & true or false &  mix of ECOM1 and ECOM2\\
		\textbf{SBOXW}  & true or  false & Simple box wing model\\
		\textbf{EMPirical models} & true or false & Empirical is independent of the other four\\
		\hline
	\end{tabular}
	\caption{POD YAML: Estimated SRP models}
	\label{table:pod_yaml_est_srp_model}
\end{table}
%
%
\begin{lstlisting}[language=xml,caption=yaml example for apriori srp model options]
srp_apriori_model:
	no_model:               false
	cannon_ball_model:      true
	simple_boxwing_model:   false
	full_boxwing_model:     false
\end{lstlisting}
%
\subsection{gravity\_model}
Type of gravity model to apply, only one option can be true.
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{central\_force}            & true or false &  \\
		\textbf{static\_gravity\_model}    & true or false &  \\
		\textbf{time\_variable\_model}     & true or false &  \\
		\textbf{iers\_geopotential\_model} & true or false &  \\
		\hline
	\end{tabular}
	\caption{POD YAML: Gravity Models}
	\label{table:pod_yaml_gravity_models}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for gravitational force model options]
gravity_model:
	central_force:           false   # Central force gravity field              : gravity_model = 0
	static_gravity_model:    false   # Static global gravity field model        : gravity_model = 1
	time_variable_model:     true    # Time-variable global gravity field model : gravity_model = 2
	iers_geopotential_model: false   # IERS conventional geopotential model     : gravity_model = 3
\end{lstlisting}
%
\subsection{stochastic pulse (pulse)}
%
Do not mix pulses in R/T/N (terrestrial) with pulses in (X/X/Z)
%
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{enabled} & true or false & then if true: \\
		\hline
		\textbf{epoch\_number} & int & number of epochs to apply pulses each day \\
		\textbf{offset} & int & seconds until the first pulse of the day \\
		\textbf{interval} & int & seconds between each pulse (after the first)\\
		\hline
		directions & & \\
		\textbf{x\_direction} &  true or false &  \\
		\textbf{y\_direction} &  true or false &  \\
		\textbf{z\_direction} &  true or false &  \\
		\textbf{r\_direction} &  true or false &  \\
		\textbf{t\_direction} &  true or false &  \\
		\textbf{n\_direction} &  true or false &  \\
\hline
	\end{tabular}
	\caption{POD YAML:stochastic pulse options}
	\label{table:pod_yaml_stochastic_pulse}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for gravitational force model options]
pulse:
enabled:      false
epoch_number:     1    # number of epochs to apply pulses
offset:       43200    # since the start of day
interval:     43200    # repeat every N seconds
directions:
	x_direction:   true
	y_direction:   true
	z_direction:   true
	r_direction:   false
	t_direction:   false
	n_direction:   false
reference_frame:
	icrf:          true
	orbital:       false
\end{lstlisting}
%
\section{EQM options}
%
\subsection{Integration Step}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{RK4\_integrator\_method} & true or false &  Do not use RK4 for veq as it is not implemented\\
		\textbf{RKN7\_integrator\_method} & true or false & only one can be true\\
		\textbf{RK8\_integrator\_method}  & true or false & \\
		\hline
		\textbf{integrator\_step} & int & step size in seconds \\
		\hline
	\end{tabular}
	\caption{POD YAML: Integration Step models}
	\label{table:pod_yaml_integration_step}
\end{table}
%

\begin{lstlisting}[language=xml,caption=yaml example for gravitational force model options]
# Numerical integration method
# Runge-Kutta-Nystrom 7th order RKN7(6): RKN7, Runge-Kutta 4th order: RK4, Runge-Kutta 8th order RK8(7)13: RK8
integration_options:
	RK4_integrator_method: false
	RKN7_integrator_method: true
	RK8_integrator_method: false
	integrator_step: 900         # Integrator stepsize in seconds
\end{lstlisting}

\subsection{Gravity Field}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{enabled} & true or false & and if true:\\
		\textbf{gravity\_degree\_max} &  & maximum model terms in spherical harmonic expansion \\
		\textbf{timevar\_degree\_max} &  & maximum time variable model terms in spherical harmonic expansion \\
		\hline
	\end{tabular}
	\caption{POD YAML: Gravity Models}
	\label{table:label_name}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for gravitational force model options]
# Gravitational Forces
gravity_field:
	enabled: true
	gravity_degree_max:      15      # Gravity model maximum degree/order (d/o)
	timevar_degree_max:      15      # Time-variable coefficients maximum d/o
\end{lstlisting}
%
\subsection{planetary\_perturbations:}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{enabled} & true or false & Uses the emphemeris \\ %TODO specify the file
		\hline
	\end{tabular}
	\caption{POD YAML: planetary perturbations}
	\label{table:pod_yaml_planet}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for planetary pertubations]
# Planetary Gravitational Forces
	planetary_perturbations:
		enabled: true
\end{lstlisting}
%
\subsection{tidal\_effects:}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{solid\_tides\_nonfreq} & True or False & frequency independent Solid Earth Tides \\
		\textbf{solid\_tides\_freq} & True or False & frequency dependent Solid Earth Tides \\
		\textbf{ocean\_tides} & True or False & uses the ocean tides file \\
		\textbf{solid\_earth\_pole\_tides} & True or False & tide induced earth spin rotation not about the centre of the ellipsoid \\
		\textbf{ocean\_pole\_tide} & True or False & ocean response to the above \\
		\textbf{ocean\_tides\_degree\_max} & True or False & maximum model term in spherical harmonic expansion \\
		\hline
	\end{tabular}
	\caption{POD YAML: tidal effects}
	\label{table:pod_yaml_tidal_effects}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for tidal effects]
  	tidal_effects:
	enabled: true
	solid_tides_nonfreq:    true   # Solid Earth Tides frequency-independent terms
	solid_tides_freq:       true   # Solid Earth Tides frequency-dependent terms
	ocean_tides:            true   # Ocean Tides
	solid_earth_pole_tides: true   # Solid Earth Pole Tide
	ocean_pole_tide:        true   # Ocean Pole Tide
	ocean_tides_degree_max: 15     # Ocean Tides model maximum degree/order
\end{lstlisting}
%
\section{relativistic\_effects:}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{enabled} & true or false & Lens Thinning, SchwarzChild and deSitter effects, there are no means to separate these effects currently. The Lens Thirring effect is calculated but subsequently ignored in the POD.\\
		\hline
	\end{tabular}
	\caption{POD YAML:relativistic\_effects}
	\label{table:pod_yaml_relativistic_effects}
\end{table}
%
\section{non\_gravitational\_effects:}
\subsection{Models to be applied:}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{solar\_radiation} & true or false & radiation push from the sun \\
		\textbf{earth\_radiation} & true or false & radiation push from the earth \\
		\textbf{antenna\_thrust}  & true or false & reverse thrust from antenna radiation \\
		\hline
	\end{tabular}
	\caption{POD YAML: non gravitational effects}
	\label{table:pod_yaml_non_grav}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for non gravitational effects]
# Non-gravitational Effects
non_gravitational_effects:
	enabled: true
	solar_radiation: true
	earth_radiation: true
	antenna_thrust:  true
\end{lstlisting}

\subsection{Empirical parameters}
\begin{table}[h!]
	\begin{tabular}{|p{4.5cm}|p{2cm}|p{3.5cm}|}
		\hline
		Option & Values & Comments \\
		\hline
		\textbf{ecom\_d\_bias} & true or false & \\
		\textbf{ecom\_y\_bias} & true or false & \\
		\textbf{ecom\_b\_bias} & true or false & \\
		\textbf{ecom\_d\_cpr} & true or false & (only ECOM1\/hybrid)\\
		\textbf{ecom\_y\_cpr} & true or false & (only ECOM1\/hybrid)\\
		\textbf{ecom\_b\_cpr} & true or false & \\
		\textbf{ecom\_d\_2\_cpr} & true or false &  (only ECOM2\/hybrid)\\
		\textbf{ecom\_d\_4\_cpr} & true or false & (only ECOM2\/hybrid) \\
		\textbf{emp\_r\_bias} & true or false & \\
		\textbf{emp\_t\_bias} & true or false & \\
		\textbf{emp\_n\_bias}  & true or false & \\
		\textbf{emp\_r\_cpr}  & true or false & \\
		\textbf{emp\_t\_cpr}  & true or false & \\
		\textbf{emp\_n\_cpr} & true or false & \\
		\textbf{cpr\_count}  & int & empirical cpr count \\
		\hline
	\end{tabular}
	\caption{POD YAML: Configuration options for solar radiation pressure models}
	\label{table:pod_yaml_srp_options}
\end{table}
%
\begin{lstlisting}[language=xml,caption=yaml example for srp parameters]
# Non-gravitational Effects
srp_parameters:
	ECOM_D_bias:  true
	ECOM_Y_bias:  true
	ECOM_B_bias:  true
	EMP_R_bias:   true
	EMP_T_bias:   true
	EMP_N_bias:   true
	ECOM_D_cpr:   true
	ECOM_Y_cpr:   true
	ECOM_B_cpr:   true
	ECOM_D_2_cpr: false
	ECOM_D_4_cpr: false
	EMP_R_cpr:    true
	EMP_T_cpr:    true
	EMP_N_cpr:    true
	cpr_count:    1
\end{lstlisting}

NB EQM and VEQ srp parameters MUST be identical. May move into pod\_options in future.
overrides are not implemented yet. Ignore for now. We imagine overrides at the system, block (sat type) and individual satellite level

\section{overides*}
\textbf{*This section has not yet been implemented in the POD, and is a placehodler for future versions.}

In this section put any system, block or PRN overrides that are different to the ones chosen before
{\small
	\begin{lstlisting}[language=xml,caption=yaml example for override]
overrides:
	system:
	GPS:
	srp_apriori_model:
	no_model:   false
	cannon_ball_model:   true
	simple_boxwing_model:   false
	full_boxwing_model:     false
	GAL:
	srp_apriori_model:
	no_model:   false
	cannon_ball_model:   false
	simple_boxwing_model:   false
	full_boxwing_model:     true
	GLO:
	srp_apriori_model:
	no_model:   false
	cannon_ball_model:   false
	simple_boxwing_model:   true
	full_boxwing_model:     false
	BDS:
	srp_apriori_model:
	no_model:   false
	cannon_ball_model:   false
	simple_boxwing_model:   true
	full_boxwing_model:     false
block:
	GPS-IIF:
		srp_apriori_model:
		no_model:   false
		cannon_ball_model:   false
		simple_boxwing_model:   true
		full_boxwing_model:     false
	# GPS BLK IIF use ECOM2 parameters
	srp_parameters:
		ECOM_D_bias:   true
		ECOM_Y_bias:   true
		ECOM_B_bias:   true
		ECOM_D_2_cpr: false
		ECOM_D_4_cpr: false
		ECOM_B_cpr:   true
prn:
	G01:
		srp_apriori_model:
			no_model:   false
			cannon_ball_model:   false
			simple_boxwing_model:   false
			full_boxwing_model:     true

	\end{lstlisting}
}

%\section{Example 1 configuration file}
%\lstinputlisting[language=xml, caption=pod example1 configuration file]{../../test/pod/ex1.yaml}
%\section{Example 2 configuration file}
%\lstinputlisting[language=xml, caption=pod example2 configuration file]{../../test/pod/ex2.yaml}
%\section{Example 3 configuration file}
%\lstinputlisting[language=xml, caption=pod example3 configuration file]{../../test/pod/ex3.yaml}
%\section{Example 4 configuration file}
%\lstinputlisting[language=xml, caption=pod example4 configuration file]{../../test/pod/ex4.yaml}
%\section{Example 5 configuration file}
%\lstinputlisting[language=xml, caption=pod example5 configuration file]{../../test/pod/ex5.yaml}


\chapter{Numeric instruction}\label{refnumeric}
\index{NUMERIC,instruction}
\index{Instructions,NUMERIC}
\index{Arithmetic,NUMERIC settings}
\index{FORM,option of NUMERIC instruction}
\index{SCIENTIFIC value for NUMERIC FORM,}
\index{ENGINEERING value for NUMERIC FORM,}
\index{DIGITS,on NUMERIC instruction}
\begin{shaded}
\begin{alltt}
\textbf{numeric digits} [\emph{exprd}];
           \textbf{form} [\textbf{scientific}];
           [\textbf{engineering}];
\end{alltt}
\end{shaded}
 The \keyword{numeric} instruction is used to change the way in which
arithmetic operations are carried out by a program.
The effects of this instruction are described in detail in the
section on  \emph{Numbers and Arithmetic} (see page \pageref{refnums}) .
\begin{description}
\item[numeric digits]\label{refndigits}

controls the precision under which arithmetic operations will be
 evaluated (see page \pageref{refndi2}) .

If no expression \emph{exprd} is given then the default value of 9
is used.
Otherwise the result of the expression is rounded, if necessary,
according to the current setting of \keyword{numeric digits} before it is
used.
The value used must be a positive whole number.
 There is normally no limit to the value for \keyword{numeric digits}
(except the constraints imposed by the amount of storage and other
resources available) but note that high precisions are likely to be
expensive in processing time.
It is recommended that the default value be used wherever possible.

Note that small values of \keyword{numeric digits} (for example, values
less than 6) are generally only useful for very specialized applications.
The setting of \keyword{numeric digits} affects all computations, so even
the operation of loops may be affected by rounding if small values are
used.

If an implementation does not support a requested value for \keyword{numeric
digits} then the instruction will fail with an exception (which may,
as usual, be caught with the \keyword{catch} clause of a control
construct).

The current setting of \keyword{numeric digits} may be retrieved with the
 \textbf{digits} special word (see page \pageref{refswdigit}) .
\item[numeric form]\label{refnform}
\index{Exponential notation,}

controls which form of  exponential notation (see page \pageref{refnfo2})  is to
be used for the results of operations.
\index{Notation,scientific}
\index{Notation,engineering}
\index{Scientific notation,}
\index{Engineering notation,}
This may be either \emph{scientific} (in which case only one,
non-zero, digit will appear before the decimal point), or
\emph{engineering} (in which case the power of ten will always be a
multiple of three, and the part before the decimal point will be in the
range 1 through 999).
The default notation is scientific.
 The form is set directly by the sub-keywords \keyword{scientific} or
\keyword{engineering}; if neither sub-keyword is given,
\keyword{scientific} is assumed.
The current setting of \keyword{numeric form} may be retrieved with the
 \textbf{form} special word (see page \pageref{refswform}) .

If an implementation does not support a requested value for \keyword{numeric
form} then the instruction will fail with an exception (which may,
as usual, be caught with the \keyword{catch} clause of a control
construct).
\end{description}

The \keyword{numeric} instruction may be used where needed as a
dynamically executed instruction in a method.

It may also appear, more than once if necessary, before the first
method in a class, in which case it forms the default setting for the
initialization of subsequent properties in the class and for all methods
in the class.  In this case, any exception due to the \keyword{numeric}
instruction is raised when the class is first loaded.

Further, one or more \keyword{numeric} instructions may be placed
before the first \keyword{class} instruction in a program; they do
not imply the start of a class.  The numeric settings then apply
to all classes in the program (except interface classes), as
though the \keyword{numeric} instructions were placed immediately
following the \keyword{class} instruction in each class (except that
they will not be traced).


% Copyright 2019 by Mark Wibrow
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.

\section{Fixed Point Arithmetic Library}

\begin{pgflibrary}{fixedpointarithmetic}
    This library provides an interface to the \LaTeX{} package |fp| for fixed
    point arithmetic. In addition to loading this library you must ensure |fp|
    is loaded, otherwise errors will occur.
\end{pgflibrary}

\subsection{Overview}

Whilst the mathematical engine that comes with \pgfname{} is reasonably fast
and flexible when it comes to parsing, the accuracy tends to be fairly low,
particularly for expressions involving many operations chained together. In
addition the range of values that can be computed is very small:
$\pm16383.99999$. Conversely, the |fp| package has a reasonably high accuracy,
and can perform computations over a wide range of values (approximately
$\pm9.999\times10^{17}$), but is comparatively slow and not very flexible,
particularly regarding parsing.

This library enables the combination of the two: the flexible parser of the
\pgfname{} mathematical engine with the evaluation accuracy of |fp|. There are,
however, a number of important points to bear in mind:
%
\begin{itemize}
    \item Whilst |fp| supports very large numbers, \pgfname{} and \tikzname{}
        do not. It is possible to calculate the result of |2^20| or
        |1.2e10+3.4e10|, but it is not possible to use these results in
        pictures directly without some ``extra work''.
    \item The \pgfname{} mathematical engine will still be used to evaluate
        lengths, such as |10pt| or |3em|, so it is not possible for an length
        to exceed the range of values supported by \TeX-dimensions
        ($\pm16383.99999$pt), even though the resulting expression is within
        the range of |fp|. So, for example, one can calculate |3cm*10000|, but
        not |3*10000cm|.
    \item Not all of the functions listed in Section~\ref{pgfmath-syntax}, have
        been mapped onto |fp| equivalents. Of those that have been, it is not
        guaranteed that functions will perform in the same way as they do in
        \pgfname. Reference should be made to the documentation for |fp|.
    \item In \pgfname, trigonometric functions such as |sin| and |cos| assume
        arguments are in degrees, and functions such as |asin| and |acos|
        return results in degrees. Although |fp| uses radians for such
        functions, \pgfname{} automatically converts arguments from degrees to
        radians, and converts results from radians to degrees, to ensure
        everything ``works properly''.
    \item The overall speed will actually be slower than using \pgfname{}
        mathematical engine. The calculating power of |fp| comes at the cost of
        an increased processing time.
\end{itemize}

\subsection{Using Fixed Point Arithmetic in PGF and \tikzname}

The following key is provided to use |fp| in \pgfname{} and \tikzname:

\begin{key}{/pgf/fixed point arithmetic=\meta{options}}
\keyalias{tikz}
    This key will set the key path to |/pgf/fixed point|, and execute
    \meta{options}. Then it will install the necessary commands so that the
    \pgfname{} parser will use |fp| to perform calculations. The best way to
    use this key is as an argument to a scope or picture. This means that |fp|
    does not always have to be used, and \pgfname{} can use its own
    mathematical engine at other times, which can lead to a significant
    reduction in the time for a document to compile.
\end{key}

Currently there are only a few keys key supported for \meta{options}:

\begin{key}{/pgf/fixed point/scale results=\meta{factor}}
    As noted above, |fp| can process a far greater range of numbers than
    \pgfname{} and \tikzname{}. In order to use results from |fp| in a
    |{pgfpicture}| or a |{tikzpicture}| they need to be scaled. When this key
    is used \pgfname{} will scale results of any evaluation by \meta{factor}.
    However, as it is not desirable for every part of every expression to be
    scaled, scaling will only take place if a special prefix |*| is used. If
    |*| is used at the beginning of an expression the evaluation of the
    expression will evaluated and then multiplied by \meta{factor}.
    %
\begin{codeexample}[preamble={\usepgflibrary{fixedpointarithmetic}}]
\begin{tikzpicture}[fixed point arithmetic={scale results=10^-6}]
\draw [help lines] grid (3,2);
\draw (0,0) -- (2,2);
\draw [red, line width=4pt] (*1.0e6,0) -- (*3.0e6,*2.0e6);
\end{tikzpicture}
\end{codeexample}

    A special case of scaling involves plots of data containing large numbers
    from files. It is possible to ``pre-process'' a file, typically using the
    application that generates the data, to either precede the relevant column
    with |*| or to perform the scaling as part of the calculation process.
    However, it may be desirable for the data in a plot to appear in a table as
    well, so, two files would be required, one pre-processed for plotting, and
    one not. This extra work may be undesirable so the following keys are
    provided:

    \begin{key}{/pgf/fixed point/scale file plot x=\meta{factor}}
        This key will scale the first column of data read from a file before it
        is plotted. It is independent of the |scale results| key.
    \end{key}

    \begin{key}{/pgf/fixed point/scale file plot y=\meta{factor}}
        This key will scale the second column of data read from a file before
        it is plotted.
    \end{key}

    \begin{key}{/pgf/fixed point/scale file plot z=\meta{factor}}
        This key will scale the third column of data read from a file before it
        is plotted.
    \end{key}
\end{key}


\section{A Smarter $\chi^2$}
\label{891_2:sec:smart_chi}

The algorithms used for full-spectrum fitting are designed to minimize
the $\chi^2$ difference between some model spectrum and our
observational data. In this $\chi^2$ calculation each wavelength
channel is given a weight equal to the inverse of the poisson noise
propagation described in section \ref{891_2:sec:data}. This type of
weighting benefits from historical momentum and ease of implementation
but ignores the fact that certain wavelength regions are
astrophysically more important than others for constraining star
formation histories. In other words, a traditional $\chi^2$
calculation gives more-or-less equal weight to all wavelength channels
despite the fact that some channels are more sensitive to differences
in models than others.

%% {\bf MAB: my question about the above paragraph is if it is true that
%%   everyone is basically using $\chi^2$ for FSF. Have you checked the
%%   literature?}

% ADE: Yes, and yes. Doesn't seem necessary to ref though

To capture this astrophysical importance we compute a weighting
spectrum that is applied to $\chi^2$ during full-spectrum
fitting. These weights are computed as the root-means-square (RMS)
difference between the model basis SSPs and therefore capture how much
each wavelength channel changes with different SSPs. For this
calculation we use the \val{0.2}{\Zsol}, \val{0.4}{\Zsol},
\val{1}{\Zsol}, and \val{2.5}{\Zsol} mono-metallicity
\citetalias{Bruzual03} diffusion k-means SSPs (see section
\ref{891_2:sec:bc03_dfk}).

%++++++++++++++++
%% {\bf MAB: by ``additional weights'' you should clarify that they are
%%   in addition to the error weights.}

Before computing the RMS, each SSP is normalized to have a flat
continuum to remove any low-order continuum shape effects from the
final weights. This step is important because the continuum shape
changes significantly with different metallicities and ages and also
because the overall continuum shape in the full-spectrum fits is
controlled largely by the extinction parameter, \tauV. The average
spectrum across all ages and metallicities is then computed and set as
the zero point for computing the final RMS spectrum. This attempt to
remove the effects of low-order spectral shape is similar to the
method of FIREFLY \citep{Wilkinson15}.

%+++++++++++
%% {\bf MAB: This would be a nice opportunity to mention FIREFLY. In
%%   essence we are looking to acheieve what they did but w/o filter the
%%   data. The only concern with saying this might be the referee asking
%%   why we didn't use FIREFLY.}

\begin{figure}
  \centering
  \includegraphics[width=\columnwidth]{891_2/figs/RMS_spec.pdf}
  \caption[RMS-based $\chi^2$ fitting
    weights]{\fixspacing\label{891_2:fig:RMS_spec}The RMS weighting
    function used to modify our $\chi^2$ fits ($R(\lambda)$ in
    Equation. \ref{891_2:eq:smart_chi}). The total RMS value is
    computed across all metallicities and ages. RMS$_Z$ is computed
    across all metallicities and is sensitive to differences between
    models with different metallicity values. Similarly,
    RMS$_\mathrm{age}$ is computed across all ages and is therefore
    more sensitive to model differences as a function of age.}
    %% The red line is the same as the
    %% green, but computed across all metallicities. The red and green
    %% lines show the quadrature sum of the individual RMS$_Z$ or
    %% RMS$_{age}$ computed across all ages or metallicities,
    %% respectively \textbf{this is almost certainly not clear}. Vertical
    %% lines show important emission (blue) and absorption (red)
    %% features.}
\end{figure}

Figure \ref{891_2:fig:RMS_spec} shows the resulting RMS spectrum along
with important spectral features. In addition to computing the RMS
across all ages and metallicities we also compute RMS spectra across
all ages at each metallicity and vice versa. The ``total'' RMS closely
matches the RMS across age, which suggests that age variations cause
the majority of the difference between different SSPs. There are also
few spectral features that have a high RMS value in \emph{only} age or
metallicity, which suggests these weights will struggle to break the
age/metallicity degeneracy.

The total RMS spectrum modifies the traditional $\chi^2$ by
\begin{equation}
\label{891_2:eq:smart_chi}
\chi^2 = \sum_{\lambda}\left(\frac{f(\lambda) -
  g(\lambda)}{\sigma(\lambda)}\zeta(\lambda)\right)^2,
\end{equation}
where $f(\lambda)$ and $g(\lambda)$ are the data and model spectra,
respectively, $\sigma(\lambda)$ is the poisson errors on $f(\lambda)$, and
$\zeta(\lambda)$ is the RMS spectrum.

%+++++++++++++
%% {\bf MAB: Discuss how to read the figure since it is almost impossible
%%   to make out the $RMS_{age}$ line. I think you want to say that is is
%%   easiest to make out the ``total'' (green) and Z (orange) curves
%%   which demonsrates that in most cases where there are strong peaks
%%   age variations dominates, particularly below 4500 \AA\. Redward
%%   there are weaker features where Z dominates. However, at every
%%   location where there is a strong peak in RMS both age and Z increase
%%   (except perhaps for Ca HK, which is weird), which already
%%   foreshadows that this weighting scheme is not going to bust the
%%   age-Z degeneracy.}

In addition to modifying our full-spectrum fits, the results shown in
Figure \ref{891_2:fig:RMS_spec} provide insight into the statistically
important differences between model spectra. The Balmer series stands
out as strong indicators of both age and metallicity, but surprisingly
the higher-order Balmer lines (\Hd, \Hg) have more power than \HB and
\Ha. This is important because in the absence of an accurate
correction for Balmer emission (\S\ref{891_2:sec:emission_corr}) these
higher order lines are less likely to be contaminated. Beyond the
Balmer series Na, Fe, Mg, and G-band absorption also have powerful
spikes in the RMS spectrum. Unfortunately the distance to NGC 891
places Na absorption right on top of the NaD sky emission line so it
cannot be used in analysis.

In many ways the index/equivalent width measurements common to
Astronomy and used in Chapter \ref{chap:891_1} can be thought of as
$\chi^2$ comparisons that are very highly tuned to specific spectral
features and therefore are highly dependent on the stellar physics
that go into producing the models. In this context it comes as no
surprise that the spectral features that differentiate our SSP models
are the same features that have been used extensively in the LICK
system to assign astrophysical parameters to observations of galaxy
and stars.

%+++++++++++++++++
%% {\bf MAB: This is a good discussion. I am trying to think whether it
%%   is surprising that \Hd and \Hg have more variation than \HB and \Ha.
%%   This may be well known, but the point about the emission correction
%%   is a good one. Note NaD also problematic because of ISM within the
%%   external galaxy. Concerning ``a ton of people'' just reference the
%%   Lick system and either give no reference or cite something like
%%   Burstein 1984.}

\begin{figure*}[t]
  \centering
%  \includegraphics[width=\textwidth]{891_2/figs/weight_comp_sys.pdf}
  \includegraphics[width=\textwidth]{891_2/figs/weight_comp_hist.pdf}
  \caption[Comparison of uncertainties between weighted and un-weighted
    fits]{\fixspacing\label{891_2:fig:weight_comp}
%% \emph{top:} Derived values of fits
%%     using the weighted $\chi^2$ described in Equation
%%     \ref{891_2:eq:smart_chi} compared to the same values derived using an
%%     un-weighted fit. The dashed lines have a slope of 1. \emph{bottom:}
    Distribution of fitting errors (\S\ref{891_2:sec:fit_err}) for fits
    using un-weighted and weighted $\chi^2$.}
\end{figure*}

%%%%
%ADE: I took out the whole discussion of systematics for now. I think
%it could be interesting, but is not necessary for the argument of why
%we don't use weighted fits.

%% To asses the benefit of using a weighted $\chi^2$ we compare results
%% produced with un-weighted fits to those produced with weighted fits,
%% checking for both systematic differences and the uncertainty distributions
%% of the fits themselves (see \S\ref{891_2:sec:fit_err}). The top
%% panels of Figure \ref{891_2:fig:weight_comp} show the systematic differences
%% between the two schemes. As expected, $A_V$ is highly correlated,
%% indicating that using a weighted $\chi^2$ does not significantly or
%% systematically shift the derived extinction, which speaks to the fact
%% that $A_V$ is mostly driven by the slope of the galaxy SED over a
%% broad wavelength range (although it is also correlated with $\tau_L$,
%% as shown in \S\ref{891_2:sec:fit_err}) and will therefore be relatively
%% insensitive to highly localized changes in $\chi^2$.

%% The middle panel of Figure \ref{891_2:fig:weight_comp} shows that, in many
%% cases, weighted fits find values for $\tau_L$ that are systematically
%% lower than those found via un-weighted fits. This offset is largest
%% for lower values of $\tau_L$, which points to Balmer lines as a likely
%% culprit. In Figure \ref{891_2:fig:RMS_spec} it is clear that the Balmer
%% lines (and in particular \HB, \Hg, and \Hd) are very strong indicators
%% of age and it is likely that the weighted fits increase the fraction
%% of Young SSPs (i.e., lowering the age) to more accurately fit the
%% depth of these lines at the expense of a worse fit in the inter-line
%% continuum where the $\chi^2$ weights are small.

%% {\bf MAB: This continues to be good discussion. I was wondering if it
%%   is possible to {\it show} your plausible conjecture that the
%%   inter-line regions are not fit a well in the weighted fits, e.g.,
%%   mean spectral residuals. I have a different interpretation of the
%%   middle panel. To my eye the correlation is excellent at the earliest
%%   and youngest ages. At intermediate ages, which just happens to be
%%   where our DFK are probably too coarse, ther is significantly more
%%   scatter.  I don't know what this is telling us but it would be nice
%%   to identify a group of outliers and again compare the mean spectral
%%   residuals between the two classes of fits.}

%% The right panel of Figure \ref{891_2:fig:weight_comp} indicates systematic
%% offsets in $Z_L$ caused by using a weighted $\chi^2$. In particular at
%% low metallicities, as reckoned by the weighted fits, the weighted fits
%% produce systematically lower values while at high metallicities (again
%% weighted by the weighted fit) the weighted fits produce systematically
%% higher values. Many of the strong metallicity indicators shown in
%% Figure \ref{891_2:fig:RMS_spec} have relatively weak amplitudes when
%% compared the uncertainty in the flux values (i.e., they have a low
%% signal to noise) and by increasing the weight in these regions we are
%% possibly pushing $\chi^2$ beyond the limits of our uncertainty. When
%% the signal in one of these metal lines is strong (i.e. high
%% metallicity) the weighted fit will attempt to accurately match the
%% depth of the feature by increasing the fraction of metal-rich SSPs
%% beyond what we be allowed by an un-weighted fit (which is relatively
%% more constrained by the ``featureless'' continuum). When there is very
%% little signal in the metal lines, however, the weighted fits are
%% forced to avoid a small level of absorption on the level of the flux
%% uncertainty that would otherwise be allowed in the un-weighted
%% fits. In other words, in the weighted fits weak metal absorption lines
%% cannot ``hide in the noise'' and therefore a lower total metallicity
%% is needed.

%% {\bf MAB: This needs to be articulated more clearly: ``we are possibly
%%   pushing $\chi^2$ beyond the limits of our uncertainty.'' I didn't
%%   follow your subsequent examples. Even with the weights, there are
%%   many lines. Noise will not make all of them artificially high or
%%   low. So why the systematic difference? And which do you think is
%% right?}

To assess the benefit of using a weighted $\chi^2$ we compare fitting
uncertainties (\S\ref{891_2:sec:fit_err}) produced by un-weighted fits to
those produced with weighted fits and find, somewhat surprisingly,
that a weighted $\chi^2$ produces significantly less precise fits.
Figure \ref{891_2:fig:weight_comp} shows that for all parameters of interest
the distribution of fit uncertainties is larger for weighted fits than
for un-weighted fits, often by a factor of $>$ 2. This level of
uncertainty is unacceptable and it is clear that weighted fits
\emph{do not} improve our ability to understand NGC 891. They are
therefore abandoned for the remainder of this work. We would like to
note, however, that these tests are in no way an exhaustive
exploration of the general concept of weighted $\chi^2$ and we
encourage future research in this topic.

%-------------------
%% {\bf MAB: We are going to need to do a better job here justifying this
%%   section. I want us to keep it in for the final paper; it should
%%   definiely be in the thesis, even as is.  For the paper we need more
%%   work.

%% The key issue that I think we have not fleshed out enough
%% is consideration of accuracy. What we have shown definitively is
%% that weighting reduces precision. This is surprising because we
%% thought we were up-weighting the regions where the astrophysical variance
%% (which is our ``signal'') was largest. In the above paragraph you
%% are starting to get at the key issue, namely with statements about
%% systematic differences (could be related to different accuracy) relative
%% to random errors. We need to do two things.

%% (1) Quantify and illustrate the level of systematics vs increased
%% random error (we've only done the latter).

%% How do the projections of $Z_L$, $\tau_L$ and $A_V$ compare for the
%% two fitting methods? Can we say one looks more astrophysically
%% plausible than another? Even if no, this is important to know. Let's
%% make the plots and look at them. Maybe one set w/ two colors for
%% points -- unless we also want to look at height and radius trends.

%% (2) Identify ways to assess if we think one method is more accurate
%% (in the mean) than the other.

%% I would start by looking at the mean residuals for the different fit
%% cases.  As noted above, we may want to do this for subsets of the data
%% where systematics in age and Z are most pronounced. It would be nice
%% to see of the scatter is different in the up-weighted vs down-weighted
%% areas, but I think the key is to identify if one fitting method
%% systematiclly over or under-estimates features or continuum.

%% Where I think we should be going with (1) and (2): While the weighted
%% fits may be noiser, it may be that they are more accurate in the
%% mean. If so this mean provides a possible systematic correction we
%% could apply to the un-weighted fits IF we thought there was some
%% reasonable way to do this. (It will depend on what we find in (1)
%% above.) If we cannot conclude that one fitting method vs the other is
%% plausibly more accurate, then at least we have quantified one
%% assessment of potential systematics in our fitting. That alone
%% justifies the section. In short, you are on the right track; we just
%% need to push it the final step.

%% Wording: ``quantities with larger systematic offsets (i.e., $Z_L$)
%% also have larger fit uncertainty, which dilutes the magnitude of the
%% offset.'' No, it doesn't dilute the magnitude of the offset but its
%% significance.

%% Last two sentences should be revised based on our additional work
%% and/or specific recommendations for future effort (for starters: what
%% we would like to do if we have time.}

%% On the other hand, a full-spectrum fit like that
%% described in \S\ref{891_2:sec:SSP_method} more accurately captures the SED
%% of a galaxy at the expense of strong constraints on the detailed
%% astrophysics. Our RMS-weighted full-spectrum fitting is designed to
%% occupy a middle ground between these two methods. With it we are able
%% to leverage our astrophysical knowledge to focus in on key regions
%% while at the same time fitting all of these regions at once along with
%% the continuum shape. It pretty much rules.


\section{Type System}
\label{sec:type}

The key to both performance and correctness in Legion is the
accuracy of the region usage declarations.  The Legion type system has been
designed to statically check that region usage declarations are adhered to.
In this section we summarize the main features of the type system; due to space limitations we omit more than
we include.
Type judgments have the form:
\begin{center}
$\Gamma, \Phi_i, C_i \vdash e : T, \Phi_o, C_o$
\end{center}
In addition to tracking the types of variables $\Gamma$, the
type environment includes the current privileges $\Phi_i$
and region constraints $C_i$.  A judgment concludes $e$ has some type $T$,
but also tells us how the evaluation of $e$ changes the privileges $\Phi_o$ and constraints $C_o$.

Table~\ref{tbl:priv_const} shows the form of the individual privileges and
constraints that make up $\Phi$ and $C$.  Privileges represent the ability to
perform some operation on a region and its subregions.  Constraints capture relationships between regions
resulting from partitioning: $a \rleq b$ if $a$ is a subregion $b$ (directly or transitively) and $a \ast b$ if
$a$ and $b$ are disjoint (e.g., because they are distinct subregions of a disjoint partition).
Our first type rule checks region reads:

\begin{center}
{\small
\begin{math}
\infrule{
\begin{array}{lc}
  \multicolumn{2}{c}{\Gamma, \Phi_1, C_1 \vdash p : T@r_1, \Phi_2, C_2} \\
  C_2 \models r_1 \le r_2 & readable(r_2) \in \Phi_2
%  \envsub{1}{1} e_1 : \rtripsub{T_1}{2}{2} \\
%  \envsub{2}{2} e_2 : \rtripsub{T_2}{3}{3}
\end{array}
}
{
  \Gamma, \Phi_1, C_1 \vdash read(r_2, p) : T, \Phi_2, C_2
%  \envsub{1}{1} e_1; e_2 : \rtripsub{T_2}{3}{3}
}
\end{math}
}
\end{center}

In order to safely read from a pointer into $r_1$, we must
provide a region $r_2$ which is known to contain $r_1$ and for which we possess
a read privilege.  Rules for region writes and reductions are similar.

Region relationships are first-class values and can be stored in data structures
and passed around the program.  However, the Legion type
system cannot afford to lose information about regions that are stored
in the heap.  To track the regions
in region relationships accurately we use existential quantification
over regions.  The quantifiers capture both types and constraints, but
not privileges.  The type of a region relation has the form:
\begin{center}
$RR = \exists r_1, \ldots, r_n.\left(T, \emptyset, C\right)$
\end{center}
Pack and unpack operations are used in the type system
to add and remove the existential quantifiers:
\begin{center}
{\small
\begin{math}
\begin{array}{c}
\infrule{
\begin{array}{l}
RR = \exists r_1, \ldots, r_n.\left(T_1, \emptyset, C_1\right) \\
\Gamma, \Phi_2, C_2 \vdash e : RR, \Phi_3, C_3  \\
r'_1, \ldots, r'_n \not\in \mathit{RegionsOf}\left(\Gamma, \Phi_3, C_3\right)
\end{array}
}{
\begin{array}{l@{}l}
\Gamma, \Phi_2, C_2 \vdash unpackrr{~}e :~  & [r'_1/r_1,\ldots,r'_n/r_n]T_1, \Phi_3, \\
& C_3 \wedge [r'_1/r_1,\ldots,r'_n/r_n]C_1
\end{array}
}
\\
\\
\infrule{
\begin{array}{l}
RR = \exists r_1, \ldots, r_n.\left(T_1, \emptyset, C_1\right) \\
\Gamma, \Phi_2, C_2 \vdash e : [r'_1/r_1,\ldots,r'_n/r_n]T_1, \Phi_3, C_3 \\
C_3 \models [r'_1/r_1,\ldots,r'_n/r_n]C_1
\end{array}
}{
\begin{array}{l}
\Gamma, \Phi_2, C_2 \vdash packrr{ }RR\mbox{ }e : RR, \Phi_3, C_3 \\
\end{array}
}
\end{array}
\end{math}
}
\end{center}
Any expression whose type is a region relationship can be unpacked.
Doing so introduces a fresh region variable into the current type
environment for each region that was bound in the quantification.  The
fresh region variables are substituted into the region relationship's
type and constraints.  Packing an expression into a region
relationship does the reverse.  If the type of an expression can be
unified with the region relationship's type and the corresponding
constraints of the region relationship can be shown to hold, the
expression can be packed into the region relationship and used
interchangeably with any other instance of that region relationship.

Although the type system uses explicit packing and unpacking operations,
these are implicit in Legion application code, such as the
circuit simulation in Listing~\ref{lst:code_ex}.  Unpacking is
inserted whenever a variable comes into scope, and packing is used
whenever a variable is written to the heap or passed as a task argument.

%Additionally, the simultaneous assignment operation essentially
%performs a pack for the result of the assignments and will also perform an
%unpack if one ore more fields of the structure are left unchanged.

\begin{table}
\centering
{\small
\begin{math}
\begin{array}{cc}
\begin{tabular}{ccc}
$\phi$ & ::= & $readable(r)$ \\
  &$\mid$&$writeable(r)$ \\
  &$\mid$&$reduceable(r,f)$ \\
%  &$\mid$&$allocable(r)$ \\
%  &$\mid$&$freeable(r)$ \\
\\
$\Phi$ & ::= & $\{ \phi_1, \ldots, \phi_n \}$
\end{tabular}
&
\begin{array}{ccc}
C & ::= & (r_1 \rleq r_2) \\
%  &\mid&(r_1 \le r_2) \\
  &\mid&(r_1 * r_2) \\
%  &\mid&(i_1 = i_2) \\
%  &\mid&(i_1 \ne i_2) \\
  &\mid&(C_1 \wedge C_2) \\
\end{array}
\end{array}
\end{math}
}
\label{tbl:priv_const}
\caption{Privileges and Constraints}
\end{table}

As mentioned above, region privileges are not stored in packed types;
instead, privileges are passed through the task call tree.  This is a key
property of the type system, and is what allows the runtime to
track which regions are in use by which tasks and to make distributed
scheduling decisions.
Each subtask must obtain its privileges from
the task that calls it.  For example, in Listing~\ref{lst:code_ex},
the task {\tt calc\_new\_currents} requires regions {\tt piece.rw\_pvt} with {\tt RW} privileges
and {\tt piece.rn\_pvt} and {\tt piece.rn\_ghost} with {\tt RO} (read-only) privileges.  Because the calling task has {\tt RW} privileges on the parent regions of these
region arguments, the type checker can confirm that the subtask can execute with the needed privileges.

%The coherence property for a task argument is always identical to the one of the parent task.

Due to the inability for a packed region relationship to hold privileges, any
useful region relationship will leave at least one region free (i.e. unquantified) and include constraints that relate the quantified region(s) to the free one(s).  As long as a task holds a privilege for the region that is kept free, the
region relationship can be unpacked and used.

%bprivilege for a given region is the \emph{newrr} operation that created that
%region, but the way in which privileges can be provided to a subtask, or
%returned to a parent task, is described in the task application rule:
%
%\begin{center}
%\begin{math}
%\begin{array}{c}
%\infrule
%{
%\begin{array}{lc}
%  \Gamma, \Phi_1, C_1 \vdash e_1 : \left(\left(T_i, \Phi_i, C_i\right) \rightarrow \exists r_1, \ldots, r_n . \left(T_o, \Phi_o, C_o\right), \Phi_2, C_2\right) \\
%  \Gamma, \Phi_2, C_2 \vdash e_2 : \left(T_i, \Phi_3, C_3\right) \\
%  r'_1, \ldots, r'_n \not\in \mathit{RegionsOf}(\Gamma, \Phi_3, C_3) \hspace{1cm}
%  \Phi_i \subset \Phi_3 \hspace{1cm}
%  C_3 \models C_i
%\end{array}
%}
%{
%\begin{array}{l@{}l}
%  \envsub{1}{1} e_1 e_2 : \rtriple{& \regionexpand T_o}{\left(\Phi_3 \cup \regionexpand \Phi_o\right)}{\\ & \left(C_3 \wedge \regionexpand C_o \wedge \bigwedge_{\substack{{\footnotesize r_f \in \{ r | \regionexpand C_o \models fresh(r) \} } \\ {\tiny r_o \in \mathit{RegionsOf}(\Gamma, \Phi_3, C_3)}}} r_f * r_o\right)}
%  \Gamma, \Phi_1, C_1 \vdash e_1 e_2 : \Big( & [r'_1/r_1,\ldots,r'_n/r_n]T_o, \\
% & \left(\Phi_3 \cup [r'_1/r_1,\ldots,r'_n/r_n] \Phi_o\right) , \\
% & \left(C_3 \wedge [r'_1/r_1,\ldots,r'_n/r_n] C_o\right) \Big)
%\end{array}
%}
%\end{array}
%\end{math}
%\end{center}
%
%In this rule, expression $e_1$ has the type of a Legion task.  In addition
%to the task's input and output types, it specifies the privileges and
%constraints that must exist at the point where the task is called.  It also
%describes the privileges and constraints that exist as post-conditions of the
%task invocation.  The output type, privileges, and constraints can be
%captured in an existential quantification, allowing a task to return one
%or more regions that were previously unknown to the caller.


\section{Radiative transfer of the atmosphere}
\label{radiative}

\subsection{Scattering}
\label{scattering}

Phase function can be interpreted as a probability distribution that must satisfy, when
integrated over $4\pi$ steradians,
\begin{equation}
  \int_{0}^{2\pi}\int_{0}^{\pi} P(\theta) \sin \theta \, d \theta \, d \phi = \int_0^\pi P(\theta) 2 \pi \sin \theta\, d \theta = 1.
  \label{phase_prob}
\end{equation}
Small objects such as molecules mostly scatter energy equally forward and backward with
a relatively simple angular pattern, while large particles such as aerosols mostly scatter
forward and typically have a complex angular pattern (see \citet{TukiainenEtAl08}).

\subsubsection{Scattering phase function}
\label{dumdidum}

Just to test subsubsection numbering.
%\lipsum[1-3]

\begin{figure}[h]
    \centering
    \includegraphics[width=0.6\textwidth]{images/sirotraje.pdf}
    \caption{Siro simulation of the photon paths in the atmosphere in limb-viewing geometry. Upper panel: view from the instrument. Lower panel: view from above.
      The simulation was run for the 30~km tangent height using 1000 photons.}
    \label{siro_trajectories}
\end{figure}