Updated and reorganised the theory file to describe the different loops used in the code.

Former-commit-id: 1826806b945282941348e9fa14889dd3b0be38ec

theory/latex/sph.tex → theory/latex/swift.tex

-\documentclass[a4paper,10pt]{article}
+\documentclass[a4paper,10pt]{report}
 \usepackage[utf8]{inputenc}
 \usepackage{amsmath}
 \usepackage{color}
 
+\newcommand{\swift}{\textsc{swift }}
+\newcommand{\eagle}{\textsc{eagle }}
+\newcommand{\gadget}{\textsc{gadget-2 }}
+
 %opening
-\title{SPH equations}
+\title{SWIFT - Theory and equations}
 \author{Matthieu}
 \begin{document}
 
 \maketitle
 
-This document does not follow the GADGET notation.\\
+
+
+
+
+\chapter{General properties}
+\label{chap:intro}
+
+The \swift code follows the model of \eagle and uses four different types of particles to represent the different
+objects present in the Universe. These different types with their \gadget names are summarized in table
+\ref{tab:parttypes}.
+
+\begin{table}[h]
+\centering
+\label{tab:parttypes}
+\begin{tabular}{|l|l|l|}
+\hline
+\textbf{Object} & \textbf{\gadget name} & \textbf{Description} \\
+\hline
+Gas & PartType0 & Particles representing the gas.\\
+DM & PartType1 & Particles representing the dark matter.\\
+Star & PartType4 & Paricles representing the stars.\\
+BH & PartType5 & Particles representing the Black Holes.\\
+\hline
+\end{tabular}
+\caption{The four types of particles present in the \swift code.}
+\end{table}
+
+All of these particles are affected by the gravitation force but additional interactions will exit for the non-DM
+particles. The number of DM particles is a constant but the number of gas, star and BH particles will vary
+over the simulation time. The latter two will tipically increase while the number of gas particles will usually
+decrease. \\
+Depending on the exact variation of the \eagle physics used, the total number of particles will be a
+constant, implying that particles will change type but none will be spawned. \\
+In a typical cosmological simulation, 50\% of the particles are DM particles, 46\% are gas particles, 4\% are star
+particles and less than 0.001\% are BH particles. These numbers can change slightly when doing a ``zoom'' simulation.\\
+
+The gas particles interact throught SPH forces which are computed through two loops over the neighbouring particles
+(Chapter \ref{chap:SPH}). The first of these loop is over all the particles within a range $h_i$ of the particle $i$
+whereas the second on is over all particles within $h_i$ and over all particles that see particle $i$ within their
+search radius $h_j$. This second loop is in principle more expensive as more neighbours have to be found. \\
+Gas particles also interact gravitationally and can take part in more complex \eagle interactions. The first of these
+\eagle modules is the cooling  which affects the particles on an individual basis. Depending on the age of the
+Universe, the chemical composition of the gas and its density, some internal energy is added or removed to the gas.
+This is done by interpolating ``cooling tables'' which have been pre-computed and yield the change of energy as a
+function of all the relevant quantities. This is a very cheap module in terms of computing.
+
+The star particles (Chapter \ref{chap:stars}) are created from gas particles when the right gas density and pressure
+criteria are met. This does not require any loop over neighbours as it is a particle by particle effect. Depdending on
+the options chosen, a gas particle can be transformed into a star particle or it can spawn one or more star particles.\\
+Once they have been created, these star particles cease to interact via SPH forces and only obey the gravity forces. \\
+The star particles evolve with time in order to reflect the change in chemical element composition of their cores.
+They dispatch elements to their gas neighbours through a loop of the same kind than the 1st SPH loop. There are in fact
+two loops performed, one to compute the weights of the neighbours and the second one to actually dispatch the elements
+and the mass. This is called ``enrichment''\\
+Finally, star particles also do feedback in the form of a packet of thermal energy given randomly to one of their
+neighbours. This process occurs only once in the lifetime of the star, shortly after its creation. The calculation of
+the weights in the enrichment parts is useful here as well. In the latest \eagle version, the amount of energy
+dispatched is a function of the velocity spread of the DM particles surrounding the star. This quantity is computed
+using, once again, a loop over the neighbours. \\
+
+
+The Black Hole particles (Chapter \ref{chap:BHs}) are created from gas particles when they hit the bottom of a potential
+well of a given depth. These particles will then do feedback in the same way that stars do it, i.e. by dumping a certain
+amount of energy to one or more neighbouring gas particles. The black hole also swallowa (i.e. destroys) gas particles
+passing by under some circumstances. This is achieved in the same loop over the neighbouring gas particles. There is no
+interaction between the BHs and the stars or DM particles. \\
+
+In summary, the various loops over different particles can be written in a short table. The
+exact equations happening in these loops are given in the corresponding sections of this document.
+
+\begin{table}[h]
+\centering
+\begin{tabular}{|l|c|c|c|c|}
+\hline
+$ \nearrow$&\textbf{DM} & \textbf{Gas} & \textbf{Stars} & \textbf{BHs} \\
+\hline
+\textbf{DM} &  &  &  &\\
+\hline
+\textbf{Gas} & \textbullet & \textbullet & &\\
+\hline
+\textbf{Stars} &\textbullet & \textbullet & &\\
+\hline
+\textbf{BHs} & & \textbullet& &\\
+\hline
+\end{tabular}
+\label{tab:interactions}
+\caption{The various loops over neighbours required by the \eagle model. For instance, gas particles are looping over
+their gas neighbours and (in another loop) over their DM neighbours. This table does not show the frequency of the
+loops. Only the gas-gas loop occurs at every time step.}
+\end{table}
+
+\textcolor{red}{DISCUSS UNIT SYSTEM !!}
+
+\chapter{Dark Matter particles}
+\label{chap:DMs}
+
+This section describes the physics of the DM particles but as all particles are affected by gravity, the equations
+apply to all four types. 
+
+\chapter{Gas particles - SPH}
+\label{chap:SPH}
 
 \section{Particle definition}
 Every particle contains the following information:
@@ -207,7 +311,7 @@ h_j$. In general, the equations are more involved as they will contain terms to
 thermal conduction. These terms are pure functions of the properties of particles $i$ and $j$ and are thus very simple
 to insert once the code is stabilized.\\
 
-The time step is given by the Courant relation where the cell size is the smoothing length and the velocitiy is the
+The time step is given by the Courant relation where the cell size is the smoothing length and the velocity is the
 signal speed:
 
 \begin{equation}
@@ -484,4 +588,16 @@ computed in the density loop and reads
 \end{equation}
 
 
+
+
+\chapter{Stars - EAGLE}
+\label{chap:stars}
+
+Blabla \eagle blablabla
+
+\chapter{Black Holes - EAGLE}
+\label{chap:BHs}
+
+Blabla \eagle blablabla
+
 \end{document}