Merge branch 'master' into eagle-cooling

Conflicts:
	Makefile.am
	configure.ac
	src/Makefile.am
	src/hydro/Gadget2/hydro_iact.h

AUTHORS

@@ -12,3 +12,4 @@ Stefan Arridge		stefan.arridge@durham.ac.uk
 Josh Borrow             joshua.borrow@durham.ac.uk
 Loic Hausammann		loic.hausammann@epfl.ch
 Yves Revaz   		yves.revaz@epfl.ch
+Jacob Kegerreis         jacob.kegerreis@durham.ac.uk

Makefile.am

@@ -19,7 +19,7 @@
 ACLOCAL_AMFLAGS = -I m4
 
 # Show the way...
-SUBDIRS = src examples doc tests 
+SUBDIRS = src examples doc tests tools
 if HAVEEAGLECOOLING
 SUBDIRS += examples/CoolingBox
 SUBDIRS += examples/CoolingRates

configure.ac

@@ -54,6 +54,19 @@ AX_COMPILER_VERSION
 #  Restrict support.
 AC_C_RESTRICT
 
+# logger
+AC_ARG_ENABLE([logger],
+	[AS_HELP_STRING([--enable-logger],
+		[enable the particle logger]
+	)],
+	[with_logger="${enableval}"],
+	[with_logger="no"]
+)
+
+if test "$with_logger" = "yes"; then
+   AC_DEFINE([WITH_LOGGER], 1, [logger enabled])
+fi
+
 # Interprocedural optimization support. Needs special handling for linking and
 # archiving as well as compilation with Intels, needs to be done before
 # libtool is configured (to use correct LD).
@@ -1137,7 +1150,7 @@ esac
 # Hydro scheme.
 AC_ARG_WITH([hydro],
    [AS_HELP_STRING([--with-hydro=<scheme>],
-      [Hydro dynamics to use @<:@gadget2, minimal, pressure-entropy, pressure-energy, default, gizmo-mfv, gizmo-mfm, shadowfax, planetary, debug default: gadget2@:>@]
+      [Hydro dynamics to use @<:@gadget2, minimal, pressure-entropy, pressure-energy, pressure-energy-monaghan, default, gizmo-mfv, gizmo-mfm, shadowfax, planetary, debug default: gadget2@:>@]
    )],
    [with_hydro="$withval"],
    [with_hydro="gadget2"]
@@ -1164,6 +1177,9 @@ case "$with_hydro" in
    pressure-energy)
       AC_DEFINE([HOPKINS_PU_SPH], [1], [Pressure-Energy SPH])
    ;;
+   pressure-energy-monaghan)
+      AC_DEFINE([HOPKINS_PU_SPH_MONAGHAN], [1], [Pressure-Energy SPH with M&M Variable A.V.])
+   ;;
    default)
       AC_DEFINE([DEFAULT_SPH], [1], [Default SPH])
    ;;
@@ -1505,7 +1521,7 @@ esac
 #  External potential
 AC_ARG_WITH([ext-potential],
    [AS_HELP_STRING([--with-ext-potential=<pot>],
-      [external potential @<:@none, point-mass, point-mass-ring, point-mass-softened, isothermal, softened-isothermal, disc-patch, sine-wave, default: none@:>@]
+      [external potential @<:@none, point-mass, point-mass-ring, point-mass-softened, isothermal, softened-isothermal, nfw, hernquist, disc-patch, sine-wave, default: none@:>@]
    )],
    [with_potential="$withval"],
    [with_potential="none"]
@@ -1520,6 +1536,12 @@ case "$with_potential" in
    isothermal)
       AC_DEFINE([EXTERNAL_POTENTIAL_ISOTHERMAL], [1], [Isothermal external potential])
    ;;
+   hernquist)
+      AC_DEFINE([EXTERNAL_POTENTIAL_HERNQUIST], [1], [Hernquist external potential])
+   ;;
+   nfw)
+      AC_DEFINE([EXTERNAL_POTENTIAL_NFW], [1], [Navarro-Frenk-White external potential])
+   ;;
    disc-patch)
       AC_DEFINE([EXTERNAL_POTENTIAL_DISC_PATCH], [1], [Disc-patch external potential])
    ;;
@@ -1560,6 +1582,7 @@ AM_CONDITIONAL([HAVEEAGLECOOLING], [test $with_cooling = "EAGLE"])
 
 # Handle .in files.
 AC_CONFIG_FILES([Makefile src/Makefile examples/Makefile examples/CoolingRates/Makefile examples/CoolingBox/Makefile doc/Makefile doc/Doxyfile tests/Makefile])
+AC_CONFIG_FILES([tools/Makefile])
 AC_CONFIG_FILES([tests/testReading.sh], [chmod +x tests/testReading.sh])
 AC_CONFIG_FILES([tests/testActivePair.sh], [chmod +x tests/testActivePair.sh])
 AC_CONFIG_FILES([tests/test27cells.sh], [chmod +x tests/test27cells.sh])
@@ -1578,8 +1601,9 @@ AC_CONFIG_FILES([tests/testFormat.sh], [chmod +x tests/testFormat.sh])
 # Save the compilation options
 AC_DEFINE_UNQUOTED([SWIFT_CONFIG_FLAGS],["$swift_config_flags"],[Flags passed to configure])
 
-# Make sure the latest git revision string gets included
-touch src/version.c
+# Make sure the latest git revision string gets included, when we are
+# working in a checked out repository.
+test -d ${srcdir}/.git && touch ${srcdir}/src/version.c
 
 #  Need to define this, instead of using fifth argument of AC_INIT, until
 #  2.64. Defer until now as this redefines PACKAGE_URL, which can emit a
@@ -1611,6 +1635,7 @@ AC_MSG_RESULT([
    CPU profiler         : $have_profiler
    Pthread barriers     : $have_pthread_barrier
    VELOCIraptor enabled : $have_velociraptor
+   Particle Logger      : $with_logger
 
    Hydro scheme       : $with_hydro
    Dimensionality     : $with_dimension

doc/RTD/source/CommandLineOptions/index.rst

+.. Command line options
+   Matthieu Schaller, 21st October 2018
+
+.. _cmdline-options:
+
+Command line options
+====================
+
+SWIFT requires a number of runtime options to run and get any sensible output.
+For instance, just running the ``swift`` binary will not use any SPH or gravity;
+the particles will just sit still!
+
+Below is a list of the command line options and when they should be used. The same list
+can be found by typing ``./swift -h``.
+
++ ``-a``: Pin runners using processor affinity.
++ ``-c``: Run with cosmological time integration.
++ ``-C``: Run with cooling.
++ ``-d``: Dry run. Read the parameter file, allocate memory but does not read
+  the particles from ICs and exit before the start of time integration. Allows
+  user to check validity of parameter and IC files as well as memory limits.
++ ``-D``: Always drift all particles even the ones far from active particles.
+  This emulates Gadget-[23] and GIZMO's default behaviours.
++ ``-e``: Enable floating-point exceptions (debugging mode).
++ ``-f``: {int} Overwrite the CPU frequency (Hz) to be used for time measurements.
++ ``-g``: Run with an external gravitational potential.
++ ``-G``: Run with self-gravity.
++ ``-M``: Reconstruct the multipoles every time-step.
++ ``-n``: {int} Execute a fixed number of time steps. When unset use the
+  time_end parameter to stop.
++ ``-o``: {str} Generate a default output parameter file.
++ ``-P``: {sec:par:val} Set parameter value and overwrites values read from the
+  parameters file. Can be used more than once.
++ ``-s``: Run with hydrodynamics.
++ ``-S``: Run with stars.
++ ``-t``: {int} The number of threads to use on each MPI rank. Defaults to 1 if
+  not specified.
++ ``-T``: Print timers every time-step.
++ ``-v``: [12] Increase the level of verbosity: 1, MPI-rank 0 writes, 2, All
+  MPI-ranks write.
++ ``-y``: {int} Time-step frequency at which task graphs are dumped.
++ ``-Y``: {int} Time-step frequency at which threadpool tasks are dumped.
++ ``-h``: Print a help message and exit.

doc/RTD/source/Cooling/index.rst

@@ -48,6 +48,16 @@ supposes an equilibrium and computes the fractions automatically.
 In order to compile SWIFT with Grackle, you need to provide the options ``with-grackle``
 and ``with-chemistry``.
 
+You will need a Grackle version later than 3.1. To compile it, run
+the following commands from the root directory of Grackle:
+``./configure; cd src/clib``.
+Update the variables ``LOCAL_HDF5_INSTALL`` and ``MACH_INSTALL_PREFIX`` in
+the file ``src/clib/Make.mach.linux-gnu``.
+Finish with ``make machine-linux-gnu; make && make install``.
+If you encounter any problem, you can look at the `Grackle documentation <https://grackle.readthedocs.io/en/latest/>`_
+
+You can now provide the path given for ``MACH_INSTALL_PREFIX`` to ``with-grackle``.
+
 Eagle
 ~~~~~
 

doc/RTD/source/ExternalPotentials/index.rst

+.. External potentials in SWIFT
+   Folkert Nobels, 25th October 2018
+   
+External Potentials 
+===================
+
+SWIFT can be run with an external potential on this page we will summarize the
+current potentials which can be run with SWIFT and how to implement your own 
+potential in SWIFT.
+
+Implemented External Potentials
+-------------------------------
+
+Currently there are several potentials implemented in SWIFT. On this page we 
+give a short overview of the potentials that are implemented in the code:
+
+1. No potential (none)
+2. Point mass potential (point-mass): classical point mass, can be placed at
+   a position with a mass.
+3. Plummer potential (point-mass-softened): in the code a softended point mass 
+   corresponds to a Plummer potential, can be placed at a position with a mass.
+4. Isothermal potential (isothermal): An isothermal potential which corresponds 
+   to a density profile which is :math:`\propto r^{-2}` and a potential which is 
+   logarithmic. This potential has as free parameters the rotation velocity 
+   and the position.
+5. Hernquist potential (hernquist): A potential that is given by the Hernquist 
+   potential: 
+   
+   :math:`\Phi(r) = - \frac{GM}{r+a}.`
+
+   The free paramters of Hernquist potential are mass, scale length,
+   and softening. The potential can be set at any position in the box.
+6. NFW potential (nfw): The most used potential to describe dark matter halos, the  
+   potential is given by:
+
+   :math:`\Phi(r) = - \frac{4\pi G \rho_0 R_s^3}{r} \ln \left( 1+ 
+   \frac{r}{R_s} \right).`
+
+   This potential has as free paramters the concentration of the DM halo, the
+   virial mass (:math:`M_{200}`) and the critical density.
+7. Sine wave (sine-wave)
+8. Point mass ring (point-mass-ring)
+9. Disc Patch (disc-patch)
+
+
+How to implement your own potential
+-----------------------------------
+
+The first step in implementing your own potential is making a directory of your
+potential in the ``src/potential`` folder and creating a file in the folder 
+called ``potential.h``.
+
+Configuring the potential 
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To get started you can copy a ``potential.h`` file from an already implemented 
+potential. In this potential the header guards (e.g. ``#IFDEF <>``) need to be 
+changed to the specific potential and the ``struct`` and 
+``potential_init_backend`` need to be  changed such that it uses your potential 
+and reads the correct potential from the parameter file during running the 
+program.
+
+Add the potential to the ``potential.h`` file in the ``src`` directory such that
+the program knows that it is possible to run with this potential.
+
+Furthermore during the configuration of the code it also needs to be clear for 
+the program that the code can be configured to run with the different 
+potentials. This means that the ``configure.ac`` file needs to be changed.
+This can be done to add an other case in the potential::
+
+  case "$with_potential" in
+     none)
+        AC_DEFINE([EXTERNAL_POTENTIAL_NONE], [1], [No external potential])
+     ;;
+     newpotential)
+        AC_DEFINE([EXTERNAL_POTENTIAL_NEWPOTENTIAL], [1], [New external potential])
+     ;;
+
+After this change it is possible to configure the code to use your new potential.
+

doc/RTD/source/GettingStarted/index.rst

@@ -20,7 +20,6 @@ and keep on your desk.
    running_example
    runtime_options
    configuration_options
-   parameter_file
    what_about_mpi
    running_on_large_systems
    special_modes

doc/RTD/source/GettingStarted/running_example.rst

@@ -19,14 +19,14 @@ as ``wget`` for grabbing the glass).
 
 
 This will run the 'SodShock' in 3D and produce a nice plot that shows you
-how the density has varied. Try running with GIZMO (this will take
+how the density has varied. Try running with GIZMO-MFV (this will take
 _significantly_ longer than with SPH) to see the difference. For that, you
 will need to reconfigure with the following options:
 
 .. code-block:: bash
    
    ./configure \
-   --with-hydro=gizmo \
+   --with-hydro=gizmo-mfv \
    --with-riemann-solver=hllc
 
 

doc/RTD/source/GettingStarted/runtime_options.rst

@@ -8,34 +8,5 @@ SWIFT requires a number of runtime options to run and get any sensible output.
 For instance, just running the ``swift`` binary will not use any SPH or gravity;
 the particles will just sit still!
 
-Below is a list of the runtime options and when they should be used. The same list
-can be found by typing ``./swift -h``.
+A list of available command line options can be found on the :ref:`cmdline-options` page.
 
-+ ``-a``: Pin runners using processor affinity.
-+ ``-c``: Run with cosmological time integration.
-+ ``-C``: Run with cooling.
-+ ``-d``: Dry run. Read the parameter file, allocate memory but does not read
-  the particles from ICs and exit before the start of time integration. Allows
-  user to check validity of parameter and IC files as well as memory limits.
-+ ``-D``: Always drift all particles even the ones far from active particles.
-  This emulates Gadget-[23] and GIZMO's default behaviours.
-+ ``-e``: Enable floating-point exceptions (debugging mode).
-+ ``-f``: {int} Overwrite the CPU frequency (Hz) to be used for time measurements.
-+ ``-g``: Run with an external gravitational potential.
-+ ``-G``: Run with self-gravity.
-+ ``-M``: Reconstruct the multipoles every time-step.
-+ ``-n``: {int} Execute a fixed number of time steps. When unset use the
-  time_end parameter to stop.
-+ ``-o``: {str} Generate a default output parameter file.
-+ ``-P``: {sec:par:val} Set parameter value and overwrites values read from the
-  parameters file. Can be used more than once.
-+ ``-s``: Run with hydrodynamics.
-+ ``-S``: Run with stars.
-+ ``-t``: {int} The number of threads to use on each MPI rank. Defaults to 1 if
-  not specified.
-+ ``-T``: Print timers every time-step.
-+ ``-v``: [12] Increase the level of verbosity: 1, MPI-rank 0 writes, 2, All
-  MPI-ranks write.
-+ ``-y``: {int} Time-step frequency at which task graphs are dumped.
-+ ``-Y``: {int} Time-step frequency at which threadpool tasks are dumped.
-+ ``-h``: Print a help message and exit.

doc/RTD/source/HydroSchemes/hopkins_sph.rst

@@ -28,3 +28,9 @@ scheme it includes a Monaghan AV scheme and a Balsara switch.
 .. code-block:: bash
    
    ./configure --with-hydro="pressure-energy"
+
+Both of the above schemes use a very simple, fixed artificial viscosity, only
+the ``SPH:viscosity_alpha`` parameter has any effect for this scheme. This will
+change the strength of the artificial viscosity throughout the simulation, and
+has a default of 0.8.
+

doc/RTD/source/HydroSchemes/minimal_sph.rst

@@ -10,11 +10,17 @@ Minimal (Density-Energy) SPH
    :caption: Contents:
 
 This scheme is a textbook implementation of Density-Energy SPH, and can be used
-as a pedagogical example. It also implements a Monaghan AV scheme, like the
-GADGET-2 scheme. It uses very similar equations, but differs in implementation
-details; namely it tracks the internal energy \(u\) as the thermodynamic
-variable, rather than entropy \(A\). To use the minimal scheme, use
+as a pedagogical example. It also implements a Monaghan AV scheme with a
+Balsara switch, like the GADGET-2 scheme. It uses very similar equations, but
+differs in implementation details; namely it tracks the internal energy \(u\)
+as the thermodynamic variable, rather than entropy \(A\). To use the minimal
+scheme, use
 
 .. code-block:: bash
 
     ./configure --with-hydro="minimal"
+
+As it uses a very simple, fixed artificial viscosity, only the
+``SPH:viscosity_alpha`` parameter has any effect for this scheme. This will
+change the strength of the artificial viscosity throughout the simulation,
+and has a default of 0.8.

doc/RTD/source/HydroSchemes/traditional_sph.rst

@@ -15,3 +15,8 @@ a Monaghan artificial viscosity scheme and Balsara switch.
 To use this hydro scheme, you need no extra configuration options -- it is the
 default!
 
+As it uses a very simple, fixed artificial viscosity, only the
+``SPH:viscosity_alpha`` parameter has any effect for this scheme. This will
+change the strength of the artificial viscosity throughout the simulation,
+and has a default of 0.8.
+

doc/RTD/source/InitialConditions/index.rst

@@ -117,15 +117,6 @@ GADGET-2 based analysis programs:
 + ``Time``, time of the start of the simulation in internal units or expressed
   as a scale-factor for cosmological runs. SWIFT ignores this and reads it from
   the parameter file.
-  
-RuntimePars
-~~~~~~~~~~~
-
-In the ``/RuntimePars/``, the following attributes are required:
-
-+ ``PeriodicBoundariesOn``, a flag to tell the code whether or not you
-  have periodic boundaries switched on. Again, this is historical; it should be
-  set to 1 (default) if you have the code running in periodic mode, or 0 otherwise.
 
 
 Particle Data
@@ -145,7 +136,7 @@ individual particle type (e.g. ``/PartType0/``) that have the following *dataset
   velocities divided by ``sqrt(a)`` (see below for a fix).
 + ``ParticleIDs``, an array of length N that are unique identifying numbers for
   each particle. Note that these have to be unique to a particle, and cannot be
-  the same even between particle types. The **IDs must be >1**. 0 or negative
+  the same even between particle types. The **IDs must be >= 0**. Negative
   IDs will be rejected by the code.
 + ``Masses``, an array of length N that gives the masses of the particles.
 
@@ -176,7 +167,9 @@ as peculiar velocities divided by ``sqrt(a)``. This can be undone by swicthing
 on the parameter ``InitialConditions:cleanup_velocity_factors`` in the
 :ref:`Parameter_File_label`.
 
-     
+
+.. _ICs_units_label:
+
 Optional Components
 -------------------
 
@@ -214,8 +207,6 @@ You should have an HDF5 file with the following structure:
      Flag_Entropy_ICs=0
      NumPart_Total=[0, 1, 0, 0, 4, 5]
      NumPart_Total_HighWord=[0, 0, 0, 0, 0, 0]
-   RuntimePars/
-     PeriodicBoundariesOn=1
    Units/
      Unit current in cgs (U_I)=1.0
      Unit length in cgs (U_L)=1.0

doc/RTD/source/NewOption/index.rst

-.. Equation of State
+.. Adding new schemes
    Loic Hausammann, 7th April 2018
 
 .. _new_option:

doc/RTD/source/ParameterFiles/index.rst

+.. Parameter Files
+   Matthieu Schaller, 21st October 2018
+
+.. _Parameter_File_label:
+
+Parameter Files
+===============
+
+File format and basic information
+---------------------------------
+
+The parameter file uses a format similar to the `YAML format
+<https://en.wikipedia.org/wiki/YAML>`_ but reduced to only the
+elements required for the SWIFT parameters. Options are given by a
+name followed by a column and the value of the parameter:
+
+.. code:: YAML
+
+   ICs:        santa_barbara.hdf5	  
+   dt_max:     1.5
+   shift:      [2., 4., 5.]
+
+Comments can be inserted anywhere and start with a hash:
+
+.. code:: YAML
+
+   # Descrption of the physics
+   viscosity_alpha:     2.0
+   dt_max:              1.5     # seconds
+
+A typical SWIFT parameter file is split into multiple sections that
+may or may not be present depending on the different configuration
+options. The sections start with a label and can contain any number of
+parameters:
+
+.. code:: YAML
+
+   Cosmology:    # Planck13
+     Omega_m:        0.307
+     Omega_lambda:   0.693
+     Omega_b:        0.0455
+     h:              0.6777
+     a_begin:        0.0078125     # z = 127
+
+The options can be integer values, floating point numbers, characters
+or strings. If SWIFT expects a number and string is given, an error
+will be raised. The code can also read an array of values:
+
+.. code:: YAML
+
+   shift:  [2., 4., 5.]
+	  
+Some options in the parameter file are optional and
+when not provided, SWIFT will run with the default value. However, if
+a compulsory parameter is missing an error will be raised at
+start-up.
+
+Finally, SWIFT outputs two YAML files at the start of a run. The first
+one ``used_parameters.yml`` contains all the parameters that were used
+for this run, **including all the optional parameters with their
+default values**. This file can be used to start an exact copy of the
+run. The second file, ``unused_parameters.yml`` contains all the
+values that were not read from the parameter file. This can be used to
+simplify the parameter file or check that nothing important was
+ignored (for instance because the code is not configured to use some
+options).
+
+The rest of this page describes all the SWIFT parameters, split by
+section. A list of all the possible parameters is kept in the file
+``examples/parameter_examples.yml``.
+
+Internal Unit System
+--------------------
+
+This section describes the units used internally by the code. This is
+the system of units in which all the equations are solved. All
+physical constants are converted to this system and if the ICs use a
+different system (see :ref:`ICs_units_label`) the particle quantities
+will be converted when read in.
+
+The system of units is described using the value of the 5 basic units
+of any system with respect to the CGS system. Instead of using a unit
+of time we use a unit of velocity as this is more intuitive. Users
+hence need to provide:
+
+* a unit of length: ``UnitLength_in_cgs``,
+* a unit of mass: ``UnitMass_in_cgs``,
+* a unit of velocity ``UnitVelocity_in_cgs``,
+* a unit of electric current ``UnitCurrent_in_cgs``,
+* a unit of temperature ``UnitTemp_in_cgs``.
+
+All these need to be expressed with respect to their cgs counter-part
+(i.e. :math:`cm`, :math:`g`, :math:`cm/s`, :math:`A` and :math:`K`). Recall
+that there are no h-factors in any of SWIFT's quantities; we, for instance,
+use :math:`cm` and not :math:`cm/h`.
+
+For instance to use the commonly adopted system of 10^10 Msun as a
+unit for mass, mega-parsec as a unit of length and km/s as a unit of
+speed, we would use:
+
+.. code:: YAML
+
+   # Common unit system for cosmo sims
+   InternalUnitSystem:
+     UnitMass_in_cgs:     1.98848e43    # 10^10 M_sun in grams
+     UnitLength_in_cgs:   3.08567758e24 # 1 Mpc in centimeters
+     UnitVelocity_in_cgs: 1e5           # 1 km/s in centimeters per second
+     UnitCurrent_in_cgs:  1             # 1 Ampere
+     UnitTemp_in_cgs:     1             # 1 Kelvin   
+	  
+Note that there are currently no variables in any of the SWIFT physics
+schemes that make use of the unit of electric current. There is also
+no incentive to use anything else than Kelvin but that makes the whole
+system consistent with any possible unit system.
+
+If one is interested in using the more humourous `FFF unit
+system <https://en.wikipedia.org/wiki/FFF_system>`_ one would use
+
+.. code:: YAML
+
+   # FFF unit system
+   InternalUnitSystem:
+     UnitMass_in_cgs:     40823.3133  # 1 Firkin (fir) in grams
+     UnitLength_in_cgs:   20116.8     # 1 Furlong (fur) in cm
+     UnitVelocity_in_cgs: 0.01663095  # 1 Furlong (fur) per Fortnight (ftn) in cm/s
+     UnitCurrent_in_cgs:  1           # 1 Ampere
+     UnitTemp_in_cgs:     1           # 1 Kelvin   
+
+The value of the physical constants in this system is left as an
+exercise for the reader [#f1]_.
+
+Cosmology
+---------
+
+When running a cosmological simulation, this section set the values of the
+cosmological model. The epanded :math:`\Lambda\rm{CDM}` parameters governing the
+background evolution of the Univese need to be specified here. These are:
+
+* The reduced Hubble constant: :math:`h`: ``h``,
+* The matter density parameter :math:`\Omega_m`: ``Omega_m``,
+* The cosmological constant density parameter :math:`\Omega_\Lambda`: ``Omega_lambda``,
+* The baryon density parameter :math:`\Omega_b`: ``Omega_b``,
+* The radiation density parameter :math:`\Omega_r`: ``Omega_r``.
+
+The last parameter can be omitted and will default to :math:`\Omega_r = 0`. Note
+that SWIFT will verify on start-up that the matter content of the initial conditions
+matches the cosmology specified in this section.
+
+This section als specifies the start and end of the simulation expressed in
+terms of scale-factors. The two parameters are:
+
+* Initial scale-factor: ``a_begin``,
+* Final scale-factor: ``a_end``.
+
+Two additional optional parameters can be used to change the equation of
+state of dark energy :math:`w(a)`. We use the evolution law :math:`w(a) =
+w_0 + w_a (1 - a)`. The two parameters in the YAML file are:
+
+* The :math:`z=0` dark energy equation of state parameter :math:`w_0`: ``w_0``
+* The dark energy equation of state evolutio parameter :math:`w_a`: ``w_a``
+
+If unspecified these parameters default to the default
+:math:`\Lambda\rm{CDM}` values of :math:`w_0 = -1` and :math:`w_a = 0`.
+
+For a Planck+13 cosmological model (ignoring radiation density as is
+commonly done) and running from :math:`z=127` to :math:`z=0`, one would hence
+use the following parameters:
+
+.. code:: YAML
+
+   Cosmology:
+     a_begin:        0.0078125     # z = 127
+     a_end:          1.0           # z = 0
+     h:              0.6777        
+     Omega_m:        0.307         
+     Omega_lambda:   0.693         
+     Omega_b:        0.0455        
+     Omega_r:        0.            # (Optional)
+     w_0:            -1.0          # (Optional)
+     w_a:            0.            # (Optional)
+
+When running a non-cosmological simulation (i.e. without the ``-c`` runtime
+flag) this section of the YAML file is entirely ignored.
+     
+Gravity
+-------
+
+The behaviour of the self-gravity solver can be modifed by the parameters
+provided in this section. The theory document puts these parameters into the
+context of the equations being solved. We give a brief overview here.
+
+* The Plummer-equivalent co-moving softening length used for all particles :math:`\epsilon_{com}`: ``comoving_softening``,
+* The Plummer-equivalent maximal physical softening length used for all particles :math:`\epsilon_{max}`: ``comoving_softening``, 
+
+At any redshift :math:`z`, the Plummer-equivalent softening length used by the
+code will be :math:`\epsilon=\min(\epsilon_{max},
+\frac{\epsilon_{com}}{z+1})`. This is expressed in internal units.
+
+* The opening angle (multipole acceptance criterion) used in the FMM :math:`\theta`: ``theta``,
+* The time-step size pre-factor :math:`\eta`: ``eta``,
+  
+The time-step of a given particle is given by :math:`\Delta t =
+\eta\sqrt{\frac{\epsilon}{|\overrightarrow{a}|}}`, where
+:math:`\overrightarrow{a}` is the particle's acceleration. Power et al. (2003) recommend using :math:`\eta=0.025`.
+The last tree-related parameter is
+
+* The tree rebuild frequency: ``rebuild_frequency``.
+
+Thqe tree rebuild frequency is an optional parameter defaulting to
+:math:`0.01`. It is used to trigger the re-construction of the tree every time a
+fraction of the particles have been integrated (kicked) forward in time.
+
+Simulations using periodic boundary conditions use additional parameters for the
+Particle-Mesh part of the calculation. The last three are optional:
+
+* The number cells along each axis of the mesh :math:`N`: ``mesh_side_length``,
+* The mesh smoothing scale in units of the mesh cell-size :math:`a_{\rm
+  smooth}`: ``a_smooth`` (default: ``1.25``),
+* The scale above which the short-range forces are assumed to be 0 (in units of
+  the mesh cell-size multiplied by :math:`a_{\rm smooth}`) :math:`r_{\rm
+  cut,max}`: ``r_cut_max`` (default: ``4.5``),
+* The scale bewlo which the short-range forces are assumed to be exactly Newtonian (in units of
+  the mesh cell-size multiplied by :math:`a_{\rm smooth}`) :math:`r_{\rm
+  cut,min}`: ``r_cut_min`` (default: ``0.1``),
+  
+For most runs, the default values can be used. Only the number of cells along
+each axis needs to be sepcified. The remaining three values are best described
+in the context of the full set of equations in the theory documents.
+  
+As a summary, here are the values used for the EAGLE :math:`100^3~{\rm Mpc}^3`
+simulation:
+
+.. code:: YAML
+	  
+   # Parameters for the self-gravity scheme for the EAGLE-100 box
+   Gravity:
+     eta:          0.025              
+     theta:        0.7                
+     comoving_softening:     0.0026994  # 0.7 proper kpc at z=2.8.
+     max_physical_softening: 0.0007     # 0.7 proper kpc
+     rebuild_frequency:      0.01       # Default optional value
+     mesh_side_length:       512       
+     a_smooth:     1.25                 # Default optional value
+     r_cut_max:    4.5                  # Default optional value
+     r_cut_min:    0.1                  # Default optional value
+
+      
+SPH
+---
+
+Time Integration
+----------------
+
+Initial Conditions
+------------------
+
+This section of the parameter file contains all the options related to
+the initial conditions. The main two parameters are
+
+* The name of the initial conditions file: ``file_name``,
+* Whether the problem uses periodic boundary conditions or not: ``periodic``.
+
+The file path is relative to where the code is being executed. These
+parameters can be complemented by some optional values to drive some
+specific behaviour of the code.
+
+* Whether to generate gas particles from the DM particles: ``generate_gas_in_ics`` (default: ``0``),
+* Whether to activate an additional clean-up of the SPH smoothing lengths: ``cleanup_smoothing_lengths`` (default: ``0``)
+
+The procedure used to generate gas particles from the DM ones is
+outlined in the theory documents and is too long for a full
+description here.  The cleaning of the smoothing lengths is an
+expensive operation but can be necessary in the cases where the
+initial conditions are of poor quality and the values of the smoothing
+lengths are far from the values they should have.
+
+When starting from initial conditions created for Gadget, some
+additional flags can be used to convert the values from h-full to
+h-free and remove the additional :math:`\sqrt{a}` in the velocities:
+
+* Whether to re-scale all the fields to remove powers of h from the quantities: ``cleanup_h_factors`` (default: ``0``),
+* Whether to re-scale the velocities to remove the :math:`\sqrt{a}` assumed by Gadget : ``cleanup_velocity_factors`` (default: ``0``).
+
+The h-factors are self-consistently removed according to their units
+and this is applied to all the quantities irrespective of particle
+types. The correct power of ``h`` is always calculated for each
+quantity.
+
+Finally, SWIFT also offers these options:
+
+* A factor to re-scale all the smoothing-lengths by a fixed amount: ``smoothing_length_scaling`` (default: ``1.``),
+* A shift to apply to all the particles: ``shift`` (default: ``[0.0,0.0,0.0]``),
+* Whether to replicate the box along each axis: ``replicate`` (default: ``1``).
+
+The shift is expressed in internal units. The option to replicate the
+box is especially useful for weak-scaling tests. When set to an
+integer >1, the box size is multiplied by this integer along each axis
+and the particles are duplicated and shifted such as to create exact
+copies of the simulation volume.
+
+The full section to start a DM+hydro run from Gadget DM-only ICs would
+be:
+
+.. code:: YAML
+   InitialConditions:
+     file_name:  my_ics.hdf5
+     periodic:                    1
+     cleanup_h_factors:           1
+     cleanup_velocity_factors:    1
+     generate_gas_in_ics:         1  
+     cleanup_smoothing_lengths:   1  
+
+  
+Physical Constants
+------------------
+
+For some idealised test it can be useful to overwrite the value of
+some physical constants; in particular the value of the gravitational
+constant. SWIFT offers an optional parameter to overwrite the value of
+:math:`G_N`. 
+
+.. code:: YAML
+
+   PhysicalConstants:
+     G:   1
+
+Note that this set :math:`G` to the specified value in the internal system
+of units. Setting a value of `1` when using the system of units (10^10 Msun,
+Mpc, km/s) will mean that :math:`G_N=1` in these units [#f2]_ instead of the
+normal value :math:`G_N=43.00927`.
+
+This option is only used for specific tests and debugging. This entire
+section of the YAML file can typically be left out. More constants may
+be handled in the same way in future versions.
+
+Snapshots
+---------
+
+Some additional specific options for the snapshot outputs are described in the
+following pages:
+
+.. toctree::
+   :maxdepth: 1
+
+   output_selection
+
+Statistics
+----------
+
+Restarts
+--------
+
+SWIFT can write check-pointing files and restart from them. The behaviour of
+this mechanism is driven by the options int he `Restarts` section of the YAML
+parameter file. All the parameters are optional but default to values that
+ensure a reasonable behaviour. 
+
+* Wether or not to enable the dump of restart files: ``enable`` (default:
+  ``1``).
+
+This parameter acts a master-switch for the check-pointing capabilities. All the
+other options require the ``enable`` parameter to be set to ``1``.
+  
+* Wether or not to save a copy of the previous set of check-pointing files:
+  ``save`` (default: ``1``),
+* Wether or not to dump a set of restart file on regular exit: ``onexit``
+  (default: ``0``),
+* The wall-clock time in hours between two sets of restart files:
+  ``delta_hours`` (default: ``6.0``).
+  
+Note that there is no buffer time added to the ``delta_hours`` value. If the
+system's batch queue run time limit is set to 6 hours, the user must specify a
+smaller value to allow for enough time to safely dump the check-point files.
+
+* The sub-directory in which to store the restart files: ``subdir`` (default:
+  ``restart``),
+* The basename of the restart files: ``basename`` (default: ``swift``)
+
+If the directory does not exist, SWIFT will create it.  When resuming a run,
+SWIFT, will look for files with the name provided in the sub-directory specified
+here. The files themselves are named ``basename_000001.rst`` where the basenme
+is replaced by the user-specified name and the 6-digits number corresponds to
+the MPI-rank. SWIFT writes one file per MPI rank. If the ``save`` option has
+been activated, the previous set of restart files will be named
+``basename_000000.rst.prev``.
+
+SWIFT can also be stopped by creating an empty file called ``stop`` in the
+directory where the code runs. This will make SWIFT dump a fresh set of restart
+file (irrespective of the specified ``delta_time`` between dumps) and exit
+cleanly. One parameter governs this behaviour:
+
+* Number of steps between two checks for the presence of a ``stop`` file:
+  ``stop_steps`` (default: ``100``).
+
+The default value is chosen such that SWIFT does not need to poll the
+file-system to often, which can take a significant amount of time on distributed
+systems. For runs where the small time-steps take a much larger amount of time,
+a smaller value is recommended to allow for a finer control over when the code
+can be stopped.
+
+Finally, SWIFT can automatically stop after a specified amount of wall-clock
+time. The code can also run a command when exiting in this fashion, which can be
+used, for instance, to interact with the batch queue system:
+
+* Maximal wall-clock run time in hours: ``max_run_time`` (default: ``24.0``),
+* Whether or not to run a command on exit: ``resubmit_on_exit`` (default:
+  ``0``),
+* The command to run on exit: ``resubmit_command`` (default: ``./resub.sh``).
+
+Note that no check is performed on the validity of the command to run. SWIFT
+simply calls ``system()`` with the user-specified command.
+
+To run SWIFT, dumping check-pointing files every 6 hours and running for 24
+hours after which a shell command will be run, one would use:
+
+.. code:: YAML
+	  
+  Restarts:
+    enable:             1          
+    save:               1          # Keep copies
+    onexit:             0          
+    subdir:             restart    # Sub-directory of the directory where SWIFT is run
+    basename:           swift      
+    delta_hours:        6.0        
+    stop_steps:         100        
+    max_run_time:       24.0       # In hours 
+    resubmit_on_exit:   1          
+    resubmit_command:   ./resub.sh 
+
+
+
+Scheduler
+---------
+
+Domain Decomposition
+--------------------
+
+.. [#f1] The thorough reader (or overly keen SWIFT tester) would find  that the speed of light is :math:`c=1.8026\times10^{12}\,\rm{fur}\,\rm{ftn}^{-1}`, Newton's contant becomes :math:`G_N=4.896735\times10^{-4}~\rm{fur}^3\,\rm{fir}^{-1}\,\rm{ftn}^{-2}` and Planck's constant turns into :math:`h=4.851453\times 10^{-34}~\rm{fur}^2\,\rm{fir}\,\rm{ftn}^{-1}`.
+
+
+.. [#f2] which would translate into a constant :math:`G_N=1.5517771\times10^{-9}~cm^{3}\,g^{-1}\,s^{-2}` if expressed in the CGS system.

doc/RTD/source/GettingStarted/parameter_file.rst → doc/RTD/source/ParameterFiles/output_selection.rst

 .. Parameter File
    Loic Hausammann, 1 june 2018
 
-.. _Parameter_File_label:
-
-Parameter File
-==============
-
-To run SWIFT, you will need to provide a ``yaml`` parameter file.  An example is
-given in ``examples/parameter_file.yml`` which should contain all possible
-parameters.  Each section in this file corresponds to a different option in
-SWIFT and are not always required depending on the configuration options and
-the run time parameters.
+.. _Output_list_label:
 
 Output List
 ~~~~~~~~~~~
 
-In the sections ``Snapshots`` and ``Statistics``, you can specify the options ``output_list_on`` and ``output_list``  which receive an int and a filename.
-The ``output_list_on`` enable or not the output list and ``output_list`` is the filename containing the output times.
-With the file header, you can choose between writing redshifts, scale factors or times.
+In the sections ``Snapshots`` and ``Statistics``, you can specify the
+options ``output_list_on`` and ``output_list`` which receive an int
+and a filename.  The ``output_list_on`` enable or not the output list
+and ``output_list`` is the filename containing the output times.  With
+the file header, you can choose between writing redshifts, scale
+factors or times.
 
 Example of file containing with times (in internal units)::
 
@@ -42,6 +36,8 @@ Example of file with redshift::
   10
   5
 
+.. _Output_selection_label:
+  
 Output Selection
 ~~~~~~~~~~~~~~~~
 

doc/RTD/source/VELOCIraptorInterface/index.rst

+.. VELOCIraptor Interface
+   Folkert Nobels, 8th October 2018
+
+VELOCIraptor Interface
+======================
+
+This section includes information on the VELOCIraptor interface implemented in
+SWIFT. There are mainly four subsection; the first section explains shortly 
+how VELOCIraptor works, the second subsection explains how to configure SWIFT
+with VELOCIraptor, the third subsection explains how to configure a standalone
+version of VELOCIraptor and the last subsection explains how the output format
+of VELOCIraptor works.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   whatis
+   stfwithswift
+   stfalone
+   output
+
+
+

doc/RTD/source/VELOCIraptorInterface/output.rst

+.. VELOCIraptor output
+   Folkert Nobels 12th of October
+
+VELOCIraptor Output
+===================
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Contents: 
+
+In general VELOCIraptor outputs six files per snapshot, of which 2 files are
+for unbound particles specifically.  In this part we will explain what is
+inside the different files.
+
+Catalog_groups file
+-------------------
+
+The first output file of VELOCIraptor is the ``.catalog_group`` file,
+this file contains all the information that is group specific, and does not go
+into depth of physical properties but only on numbers of particles and 
+group sizes, the interesting data in the ``.catalog_group`` files are: 
+
++ The ``group_size``: gives a list of all the halos and the number of particles
+  in the halo, this list is numbered from 0 until the number of groups minus
+  one. It is important that the groups are not ordered in any way [#order]_.
+  It is also important to note that the group size includes both the bound and
+  unbound particles; always use the ``Offset`` and ``Offset_unbound`` data
+  when reading from the ``catalog_particles`` files.
++ The ``Num_of_groups`` or ``Total_num_of_groups``: gives the total number of
+  groups in the snapshot.
++ The ``Offset`` list: This list gives the offset off the particles. In the
+  output of VELOCIraptor there is no file which has an ID for every particle
+  and a corresponding group, rather the particles are ordered according to in
+  which group they are. So if we want to access the particles in group 0, we
+  need to look at the particles from ``Offset[0]`` until ``Offset[1]`` in the
+  ``.catalog_particles`` hdf5 file. In general this means that for group N we
+  need to look at particles ``Offset[N]`` until ``Offset[N+1]``. 
++ The ``Offset_unbound`` list: This list works exactly the same as the
+  ``Offset`` list only this list is for the gravitational unbound particles.
+
+Catalog_particles file
+----------------------
+
+The second file that is produced by VELOCIraptor is the ``.catalog_particles``
+file, this file contains mainly all the IDs of the particles and has two
+interesting parameters:
+
++ The ``Num_of_particles_in_groups`` and ``Num_of_particles_in_groups``
+  parameter: Gives the total number of particles in the file or the total 
+  number of particles that are in halos.
++ The ``Particle_IDs``: The list of particles as sorted by halo, in which halo
+  the individual particles are present can be found by using the
+  ``.catalog_group`` file and the corresponding ``Offset`` list. 
+
+Besides the ``.catalog_particles`` file, there is also a
+``.catalog_particles.unbound`` file, this file contains the same information
+but only for the unbound particles, a particle can only be present in one of
+these two lists. 
+
+Extracting the particles in a given halo
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``.catalog_particles`` file returns particle IDs that need to be matched
+with those in your snapshot to find the particles in the file that you
+wish to extract. The python snippet below should give you an idea of how to
+go about doing this for the bound particles.
+
+First, we need to extract the offset from the ``.catalog_group`` file, and
+work out how many _bound_ partices are in our halo. We can do this by
+looking at the next offset. Then, we can ID match those with the snapshot
+file, and get the mask for the _positions_ in the file that correspond
+to our bound particles. (Note this requires ``numpy > 1.15.0``).
+
+.. code-block:: python
+   :linenos:
+
+   import numpy as np
+   import h5py
+
+   snapshot_file = h5py.File("swift_snapshot.hdf5", "r")
+   group_file = h5py.File("velociraptor_output.catalog_group", "r")
+   particles_file = h5py.File("velociraptor_output.catalog_particles", "r")
+
+   halo = 100
+   # Grab the start position in the particles file to read from
+   halo_start_position = group_file["Offset"][halo]
+   halo_end_position = group_file["Offset"][halo + 1]
+   # We're done with that file now, best to close earlier rather than later
+   group_file.close()
+
+   # Get the relevant particle IDs for that halo; this includes particles
+   # of _all_ types.
+   particle_ids_in_halo = particles_file["Particle_IDs"][
+       halo_start_position:halo_end_position
+   ]
+   # Again, we're done with that file.
+   particles_file.close()
+
+   # Now, the tricky bit. We need to create the correspondance between the
+   # positions in the snapshot file, and the ids.
+
+   # Let's look for the dark matter particles in that halo.
+   particle_ids_from_snapshot = snapshot_file["PartType1/ParticleIDs"][...]
+
+   _, indices_v, indices_p = np.intersect1d(
+       particle_ids_in_halo,
+       particle_ids_from_snapshot,
+       assume_unique=True,
+       return_indices=True,
+   )
+
+   # indices_p gives the positions in the particle file where we will find
+   # the co-ordinates that we're looking for! To get the positions of all of
+   # those particles,
+   particle_positions_in_halo = snapshot_file["PartType1/Coordinates"][indices_p]
+
+
+Catalog_parttypes file
+----------------------
+
+The third file that is produced by VELOCIraptor is the ``.catalog_parttypes``
+file, this file contains the information what type of particle every particle
+is, it is ordered the same as the ``Particle_IDs`` in ``.catalog_particles``. 
+There are only two interesting parameters of the file which are:
+
++ The ``Num_of_particles_in_groups`` parameter: Gives the total number of
+  particles in the file which are in a halo.
++ The ``Particle_types`` list: Gives a list of particles types similar to the
+  snap shots (0 - gas, 1 - dm, 4 - stars).
+
+Besides the ``.catalog_parttypes`` file, there is also a
+``.catalog_parttypes.unbound`` file, this file contains this information for
+the unbound particles.
+
+Properties file
+---------------
+
+The Fourth file is the ``.properties`` file, this file contains many physical
+useful information of the corresponding halos. This can be divided in several
+useful groups of physical parameters, on this page we have divided the several
+variables which are present in the ``.properties`` file. This file has most 
+physical interesting parameters of the halos.
+
+Mass-Radius determination:
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``.properties`` file contains many ways to determine the size and mass 
+of the halos, in this subsection we will list several available variables in
+the output of VELOCIraptor and we list several mass and radius parameters in
+the output which are not classified as a mass-radius pair.
+
+Critical Density related:
+"""""""""""""""""""""""""
+
++ ``Mass_200crit``: The mass of a halo with an over density on average of
+  :math:`\Delta=200` based on the critical density of the Universe 
+  (:math:`M_{200}`).
++ ``R_200crit``: The :math:`R_{200}` radius of the halo based on the 
+  critical density of the Universe
+
+Mean Density related:
+"""""""""""""""""""""
+
++ ``Mass_200mean``: The mass of a halo with an over density on average of
+  :math:`\Delta=200` based on the mean density of the Universe 
+  (:math:`M_{200}`).
++ ``R_200mean``: The :math:`R_{200}` radius of the halo based on the 
+  mean density ofthe Universe.
+
+Virial properties:
+""""""""""""""""""
+
++ ``Mvir``: The virial mass of the halos.
++ ``Rvir``: The virial radius of the halo (:math:`R_{vir}`).
+
+Bryan and Norman 1998 properties:
+"""""""""""""""""""""""""""""""""
+
++ ``Mass_BN98``, The Bryan and Norman (1998) determination of the mass of the
+  halo [#BN98]_. 
++ ``R_BN98``, the Bryan and Norman (1998) corresponding radius[#BN98]_.
+
+Several Mass types:
+"""""""""""""""""""
+This is a list of masses which cannot be categorized as easy as the other 
+properties.
+
++ ``Mass_FOF``: The friends-of-friends mass of the halos.
++ ``M_gas``: The gas mass in the halo.
++ ``Mass_tot``: The total mass of the halo
++ ``M_gas_30kpc``: The gas mass within 30 kpc of the halo centre.
++ ``M_gas_500c``: The gas mass of the overdensity of 500 times the critical
+  density
++ ``M_gas_Rvmax``: The gas mass within the maximum rotation velocity.
+
+Several Radius types:
+"""""""""""""""""""""
+
++ ``R_HalfMass``: Radius of half the mass of the halo.
++ ``R_HalfMass_gas``: Radius of half the gas mass of the halo.
++ ``R_size``:
++ ``Rmax``: 
+
+Mass Structure of the Halos:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this subsection we listed the properties of the halos that are determining 
+the mass structure of the halo, so the exact profile and the inertia tensor.
+
+NFW profile properties:
+"""""""""""""""""""""""
++ ``Xc``, ``Yc`` and ``Zc``: The x,y and z centre positions of the
+  halos.
+  
+  Centres are calculated using first all particles belonging to the
+  structure and then VELOCIraptor uses shrinking spheres to iterate to
+  a centre, stopping once the sphere contains <10% of all the
+  particles (this value can be changed to smaller amounts and there is
+  also a minimum particle number which can also be changed).
+  
++ ``Xc_gas``, ``Yc_gas``, ``Zc_gas``: The offset of the centre
+  positions of the halo based on the gas, to find the position of the
+  gas the offsets need to be added to ``Xc``, ``Yc`` and ``Zc``.
+
++ ``cNFW``: The concentration of the halo.
+
+  This is calculated using Vmax and Vvir, not using a fitted profile.
+  
++ ``VXc``, ``VYc`` and ``VZc`` are the velocities in the centre of the halo
+  [#check]_.
++ ``VXc_gas``, ``VYc_gas`` and ``VZc_gas`` are the velocities of the gas  in
+  the centre of the halo [#check]_.
+
+Intertia Tensor properties:
+"""""""""""""""""""""""""""
+
++ ``eig_ij``: Are the normalized eigenvectors of the inertia tensor.
++ The eigenvalue ratios: 
+
+  1. ``q`` is the semi-major over major; 
+  2. ``s`` is the minor over major.
+
++ ``eig_ij_gas``: Are the normalized eigenvectors of the inertia tensor for
+  only the gas particles.
++ The eigenvalue ratios for only the gas, similar to all particles:
+
+  1. ``q_gas`` is the semi-major over major for only gas; 
+  2. ``s_gas`` is the minor over major for only gas.
+
+Dynamical Structure of the Halos:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this subsection we list several properties that determine the dynamical
+structure of the halo, like the angular momentum and the velocity dispersion
+tensor.
+
+Angular momentum and spin parameters:
+"""""""""""""""""""""""""""""""""""""
+
++ ``lambda_b`` is the bullock spin parameter, see the paper by Bullock et al.
+  (2001) [#Bullock]_. 
++ ``Lx``, ``Ly`` and ``Lz`` are the angular momentum of the halos, the 
+  calculation includes all the particle types.
++ ``Lx_gas``, ``Ly_gas`` and ``Lz_gas`` are the angular momentum for only 
+  the gas particles in the snapshot.
+
+Velocity Dispersion related:
+""""""""""""""""""""""""""""
+
++ The complete velocity dispersion tensor (:math:`\sigma_{ij}`) which has 
+  an array per component which gives the value for all the halos. In 
+  general these components are called ``veldisp_ij`` in which i and j are 
+  given by ``x``, ``y`` or ``z``. This means that there are nine 
+  components stored in the ``.properties`` file. This omits the fact 
+  that the dispersion tensor by nature is a symmetric tensor. All the 
+  components are given by: 
+  ``veldisp_xx``, ``veldisp_xy``, ``veldisp_xz``, ``veldisp_yx``, 
+  ``veldisp_yy``, ``veldisp_yz``, ``veldisp_zx``, ``veldisp_zy``, 
+  and ``veldisp_zz`` [#velodisp]_.
++ ``sigV``, the scalar velocity dispersion which corresponds with the 
+  trace of the velocity dispersion tensor 
+  (:math:`\sigma = \text{Tr}(\sigma_{ij})`).
+
+
+Energy properties of the halos:
+"""""""""""""""""""""""""""""""
+
++ ``Ekin``, the kinetic energy of the halo.
++ ``Epot``, the potential energy of the halo.
++ ``Krot``, the rotational energy of the halo.
++ ``Krot_gas``, the rotational energy of the gas in the halo.
+
+
+Halo and subhalo abstract variables:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this subsection we list the ID convention for subhalos and halos and 
+some other abstract quantities of the halo which are not physical but 
+rather properties of the simulations.
+
+Structure types:
+""""""""""""""""
+
++ ``ID`` is the halo ID.
++ ``Structuretype`` is the parameter that indicates what kind of structure 
+  the current halo is. Halos have a structure type of ``10`` and subhalos
+  have a structure type of ``15``.
++ ``hostHaloID``, indicates the halo ID number of the host halo, in the case
+  that the halo has no parent (e.g. is the largest halo), the hostHaloID will
+  be ``-1``.
++ ``numSubStruct``, the number of substructures or subhalos in the halo.
+
+Particle types:
+"""""""""""""""
+
++ ``npart`` is the number of particles in the halo (all types of particles).
++ ``n_gas`` is the number of gas particles in the halo.
+
+Not specified parameters:
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this section we list parameters which cannot specifically be classified 
+in a group.
+
+
+Most Bound Particle (MBP):
+""""""""""""""""""""""""""
+
++ ``ID_mbp``, the ID of the most bound particle in the halo.
++ ``Xcmbp``, ``Ycmbp`` and ``Zcmbp`` are the positions of the most bound 
+  halo particle [#check]_.
++ ``VXcmbp``, ``VYcmbp`` and ``VZcmbp`` are the velocities of the most bound
+  halo particle [#check]_.
+
+.. [#order] In most cases more massive groups appear earlier in the list, but 
+   this is not guaranteed for larger simulations. The order of the groups is 
+   more a matter of the way that VELOCIraptor searches instead of a physical 
+   reason.
+.. [#center] This is not the average positions of the halos particles, but
+   the halo position found by the VELOCIraptor algorithm. This includes a 
+   fit for all the parameters including the gas particles or other types of
+   particles.
+.. [#velodisp] In the velocity dispersion tensor ( :math:`\sigma_{ij}` )  
+   the following relations are satisfied between components:
+
+   + :math:`\sigma_{xy}=\sigma_{yx}`
+   + :math:`\sigma_{xz}=\sigma_{zx}`
+   + :math:`\sigma_{yz}=\sigma_{yz}`
+.. [#Bullock] The Bullock spin parameter is given by 
+   :math:`\lambda = \frac{J}{\sqrt{2}MVR}`, for more information see 
+   https://arxiv.org/abs/astro-ph/0011001. 
+.. [#BN98] The Bryan and Norman (1998) paper can be found here: 
+   https://arxiv.org/abs/astro-ph/9710107
+.. [#check] Needs to be checked.

doc/RTD/source/VELOCIraptorInterface/stfalone.rst

+.. VELOCIraptor stand alone 
+   Folkert Nobels 12th October 2018
+
+Stand alone VELOCIraptor configuration
+======================================
+
+
+.. toctree::    
+   :maxdepth: 2    
+   :hidden:    
+   :caption: Contents: 
+   
+Besides running VELOCIraptor on the fly when using SWIFT, it is also possible
+to run VELOCIraptor alone without using SWIFT. In this section we explain how 
+VELOCIraptor can be run stand alone without using SWIFT.
+
+Setting up VELOCIraptor
+-----------------------
+
+The first step is setting up VELOCIraptor, this requires us to download the 
+git repository as::
+  
+  git clone https://github.com/pelahi/VELOCIraptor-STF
+
+Similar to the SWIFT with VELOCIraptor configuration, we can use the 
+swift-interface branch to analyse individual snapshots. We can use this branch
+by doing::
+
+  cd VELOCIraptor-STF
+  git fetch
+  git checkout swift-interface
+
+Again we need to copy the default SWIFT config file to a other config file by
+doing::
+
+  cd stf
+  cp Makefile.config.SWIFT-template Makefile.config
+
+Similar to configuring VELOCIraptor with swift we need to change the first 20
+lines of ``Makefile.config`` to work with our compiler, but we also need to 
+change the fact that we do not use the swift-interface but the standalone 
+version of the code, so change ``SWIFTINTERFACE="on"`` to 
+``SWIFTINTERFACE="off"``.
+
+Compiling VELOCIraptor
+----------------------
+
+Compoling goes completely different as compared to the on the fly halo finder
+configuration with SWIFT. In this case we can compile the code as::
+
+  make 
+
+After this an additional folder is created in ``VELOCIraptor-stf/stf`` called
+``bin``, in which the binary files of ``stf-gas`` is present (assuming you 
+run a simulation with SPH [#nosph]_)
+
+Running VELOCIraptor on a Snapshot
+----------------------------------
+
+After the code is compile the next step is using VELOCIraptor on a single 
+snapshot of a simulation. The code has several options which can be used, which
+can be displayed by running a terminal command of an invalid letter like::
+
+  ./stf-gas -h
+
+which gives the information about the usage of the command::
+
+  USAGE:
+
+  -C <configuration file (overrides other options)> 
+  -I <input format [Gadget (Default) 1, HDF (if implemented)2, TIPSY 3, RAMSES 4, HDF 2, NCHILADA 5>
+  -i <input file> 
+  -s <number of files per output for gadget input 1 [default]>
+  -Z <number of threads used in parallel read (1)>
+  -o <output filename>
+   ===== EXTRA OPTIONS FOR GADGET INPUT ====== 
+  -g <number of extra sph/gas blocks for gadget>
+  -s <number of extra star blocks for gadget>
+  -b <number of extra bh blocks for gadget>
+   ===== EXTRA OPTIONS REQUIRED FOR RAMSES INPUT ====== 
+  -t <ramses snapnumber>
+
+After this we can run a VELOCIraptor on a snapshot as::
+  
+  ./stf-gas -i input -o output -C configfile.txt
+
+
+.. [#nosph] In the case that in the ``Makefile.config`` it is indicate that the 
+   simulation does only contain dark matter this will reflect back on the 
+   generated binary file. So ``stf-gas`` will change to ``stf`` in the case of 
+   a dark matter only simulation.
+

doc/RTD/source/VELOCIraptorInterface/stfwithswift.rst

+.. SWIFT with VELOCIraptor
+   Folkert Nobels 12th October 2018
+
+
+Configuring SWIFT with VELOCIraptor
+===================================
+
+.. toctree::    
+   :maxdepth: 2    
+   :hidden:    
+   :caption: Contents:
+
+In the following three paragraphs we will explain how to setup VELOCIraptor,
+how to compile it and how to compile SWIFT with VELOCIraptor. 
+
+
+Setting up VELOCIraptor
+-----------------------
+
+Before we can run SWIFT with VELOCIraptor we first need to download
+VELOCIraptor. This can be done by cloning the repository on GitHub_::
+
+  git clone https://github.com/pelahi/VELOCIraptor-STF
+
+Currently the best version that works with SWIFT is the swift-interface branch
+of VELOCIraptor, to get this branch use::
+
+  cd VELOCIraptor-STF 
+  git fetch 
+  git checkout swift-interface
+
+To get the default that works with SWIFT simply copy the SWIFT template file in
+the ``Makefile.config``::
+
+  cd stf 
+  cp Makefile.config.SWIFT-template Makefile.config
+
+Depending on your compiler you want to change the first 20 lines of your
+``Makefile.config`` to work with your compiler and whether you want to use MPI
+or not. 
+
+
+Compiling VELOCIraptor
+----------------------
+
+After we downloaded the files and made a configuration file we can compile
+VELOCIraptor as follows::
+
+  make lib 
+  make libstf
+
+After the compilation of your code, there is an additional folder created in
+the ``VELOCIraptor-stf/stf`` directory called ``lib`` this directory has the
+library of VELOCIraptor and is required to run SWIFT with
+VELOCIraptor. Note that VELOCIraptor needs a serial version of the
+HDF5 library, not a parallel build.
+
+Compiling SWIFT
+---------------
+The next part is compiling SWIFT with VELOCIraptor and assumes you already
+downloaded SWIFT from the GitLab_, this can be done by running::
+
+  ./autogen.sh 
+  ./configure --with-velociraptor=/path/to/VELOCIraptor-STF/stf/lib 
+  make 
+
+In which ``./autogen.sh`` only needs to be run once after the code is cloned
+from the GitLab_, and ``/path/to/`` is the path to the ``VELOCIraptor-STF``
+directory on your machine. In general ``./configure`` can be run with other
+options as desired. After this we can run SWIFT with VELOCIraptor, but for this
+we first need to add several lines to the yaml file of our simulation::
+
+    
+  #structure finding options
+  StructureFinding:
+  config_file_name:     stf_input_6dfof_dmonly_sub.cfg
+  basename:             ./stf
+  output_time_format:   1
+  scale_factor_first:   0.02
+  delta_time:           1.02
+
+In which we specify the ``.cfg`` file that is used by VELOCIraptor and the 
+other parameters which SWIFT needs to use. In the case of 
+the Small Cosmological Volume DMO example we can run a simulation with halo
+finder as::
+
+  cd examples/SmallCosmoVolume_DM 
+  ../swift -c -s -G -x -t 8 small_cosmo_volume_dm.yml
+
+In which there is an additional ``-x`` option which activates the VELOCIraptor
+interface.
+
+
+.. _GitHub: https://github.com/pelahi/VELOCIraptor-STF
+.. _GitLab: https://gitlab.cosma.dur.ac.uk/swift/swiftsim