diff --git a/doc/RTD/source/NewOption/index.rst b/doc/RTD/source/NewOption/index.rst
index 441cd860ed79dabad2005b39ae4549d1496ab98d..08f1ff04efa9508145c1f7e04d72d2f40fe22f0d 100644
--- a/doc/RTD/source/NewOption/index.rst
+++ b/doc/RTD/source/NewOption/index.rst
@@ -7,8 +7,8 @@ General information for adding new schemes
==========================================
The following steps are required for any new options (such as new
-:ref:`hydro`, :ref:`chemistry`, :ref:`cooling`,
-:ref:`equation_of_state`, :ref:`stars` or :ref:`gravity`)
+:ref:`hydro`, chemistry, cooling,
+:ref:`equation_of_state`, stars, or gravity)
In order to add a new scheme, you will need to:
diff --git a/doc/RTD/source/ParameterFiles/index.rst b/doc/RTD/source/ParameterFiles/index.rst
index 0e0a6249cd942f5ffd3d856789b279e468d91023..488e8d37d7fa530f6dcd536f6bb39debeaab9f25 100644
--- a/doc/RTD/source/ParameterFiles/index.rst
+++ b/doc/RTD/source/ParameterFiles/index.rst
@@ -1,639 +1,18 @@
.. Parameter Files
- Matthieu Schaller, 21st October 2018
+ Josh Borrow 22nd January 2019
.. _Parameter_File_label:
Parameter Files
===============
-.. _Parameters_basics:
+This section desrcibes the options that are available in the
+parameter files.
-File format and basic information
----------------------------------
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
-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:
+ parameter_description
+ output_selection
-.. 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
-
- # Description 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 left unspecified 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``.
-
-.. _Parameters_units:
-
-Internal Unit System
---------------------
-
-The ``InternalUnitSystem`` 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 the snapshots' ref:`ICs_units_label` section of the documentation)
-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 humorous `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]_.
-
-.. _Parameters_cosmology:
-
-Cosmology
----------
-
-When running a cosmological simulation, the section ``Cosmology`` sets the values of the
-cosmological model. The expanded :math:`\Lambda\rm{CDM}` parameters governing the
-background evolution of the Universe 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 also 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 evolution 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`` run-time
-flag) this section of the YAML file is entirely ignored.
-
-.. _Parameters_gravity:
-
-Gravity
--------
-
-The behaviour of the self-gravity solver can be modified by the parameters
-provided in the ``Gravity`` 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``.
-
-The 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 below 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 specified. 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
-
-
-.. _Parameters_SPH:
-
-SPH
----
-
-.. _Parameters_time_integration:
-
-Time Integration
-----------------
-
-The ``TimeIntegration`` section is used to set some general parameters related to time
-integration. In all cases, users have to provide a minimal and maximal time-step
-size:
-
-* Maximal time-step size: ``dt_max``
-* Minimal time-step size: ``dt_min``
-
-These quantities are expressed in internal units. All particles will have their
-time-step limited by the maximal value on top of all the other criteria that may
-apply to them (gravity acceleration, Courant condition, etc.). If a particle
-demands a time-step size smaller than the minimum, SWIFT will abort with an
-error message. This is a safe-guard against simulations that would never
-complete due to the number of steps to run being too large.
-
-When running a non-cosmological simulation, the user also has to provide the
-time of the start and the time of the end of the simulation:
-
-* Start time: ``time_begin``
-* End time: ``time_end``
-
-Both are expressed in internal units. The start time is typically set to ``0``
-but SWIFT can handle any value here. For cosmological runs, these values are
-ignored and the start- and end-points of the runs are specified by the start and
-end scale-factors in the cosmology section of the parameter file.
-
-Additionally, when running a cosmological volume, advanced users can specify the
-value of the dimensionless pre-factor entering the time-step condition linked
-with the motion of particles with respect to the background expansion and mesh
-size. See the theory document for the exact equations.
-
-* Dimensionless pre-factor of the maximal allowed displacement:
- ``max_dt_RMS_factor`` (default: ``0.25``)
-
-This value rarely needs altering.
-
-A full time-step section for a non-cosmological run would be:
-
-.. code:: YAML
-
- TimeIntegration:
- time_begin: 0 # Start time in internal units.
- time_end: 10. # End time in internal units.
- dt_max: 1e-2
- dt_min: 1e-6
-
-Whilst for a cosmological run, one would need:
-
-.. code:: YAML
-
- TimeIntegration:
- dt_max: 1e-4
- dt_min: 1e-10
- max_dt_RMS_factor: 0.25 # Default optional value
-
-.. _Parameters_ICs:
-
-Initial Conditions
-------------------
-
-The ``InitialConditions`` 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
-
-
-.. _Parameters_constants:
-
-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.
-
-.. _Parameters_snapshots:
-
-Snapshots
----------
-
-The ``Snapshots`` section of the parameter file contains all the options related to
-the dump of simulation outputs in the form of HDF5 :ref:`snapshots`. The main
-parameter is the base name that will be used for all the outputs in the run:
-
-* The base name of the HDF5 snapshots: ``basename``.
-
-This name will then be appended by an under-score and 4 digits followed by
-``.hdf5`` (e.g. ``base_name_1234.hdf5``). The 4 digits are used to label the
-different outputs, starting at ``0000``. In the default setup the digits simply
-increase by one for each snapshot. However, if the optional parameter
-``int_time_label_on`` is switched on, then we use 6 digits and these will the
-physical time of the simulation rounded to the nearest integer
-(e.g. ``base_name_001234.hdf5``) [#f3]_.
-
-The time of the first snapshot is controlled by the two following options:
-
-* Time of the first snapshot (non-cosmological runs): ``time_first``,
-* Scale-factor of the first snapshot (cosmological runs): ``scale_factor_first``.
-
-One of those two parameters has to be provided depending on the type of run. In
-the case of non-cosmological runs, the time of the first snapshot is expressed
-in the internal units of time. Users also have to provide the difference in time
-(or scale-factor) between consecutive outputs:
-
-* Time difference between consecutive outputs: ``delta_time``.
-
-In non-cosmological runs this is also expressed in internal units. For
-cosmological runs, this value is *multiplied* to obtain the
-scale-factor of the next snapshot. This implies that the outputs are
-equally space in :math:`\log(a)` (See :ref:`Output_list_label` to have
-snapshots not regularly spaced in time).
-
-When running the code with structure finding activated, it is often
-useful to have a structure catalog written at the same simulation time
-as the snapshots. To activate this, the following parameter can be
-switched on:
-
-* Run VELOCIraptor every time a snapshot is dumped: ``invoke_stf``
- (default: ``0``).
-
-This produces catalogs using the options specified for the stand-alone
-VELOCIraptor outputs (see the section :ref:`Parameters_structure_finding`) but
-with a base name and output number that matches the snapshot name
-(e.g. ``stf_base_name_1234.hdf5``) irrespective of the name specified in the
-section dedicated to VELOCIraptor. Note that the invocation of VELOCIraptor at
-every dump is done additionally to the stand-alone dumps that can be specified
-in the corresponding section of the YAML parameter file.
-
-Users can optionally specify the level of compression used by the HDF5 library
-using the parameter:
-
-* GZIP compression level of the HDF5 arrays: ``compression`` (default: ``0``).
-
-The default level of ``0`` implies no compression and values have to be in the
-range :math:`[0-9]`. This integer is passed to the i/o library and used for the
-lossless GZIP compression algorithm. Higher values imply higher compression but
-also more time spent deflating and inflating the data. Note that up until HDF5
-1.10.x this option is not available when using the MPI-parallel version of the
-i/o routines.
-
-Finally, it is possible to specify a different system of units for the snapshots
-than the one that was used internally by SWIFT. The format is identical to the
-one described above (See the :ref:`Parameters_units` section) and read:
-
-* a unit of length: ``UnitLength_in_cgs`` (default: ``InternalUnitSystem:UnitLength_in_cgs``),
-* a unit of mass: ``UnitMass_in_cgs`` (default: ``InternalUnitSystem:UnitMass_in_cgs``),
-* a unit of velocity ``UnitVelocity_in_cgs`` (default: ``InternalUnitSystem:UnitVelocity_in_cgs``),
-* a unit of electric current ``UnitCurrent_in_cgs`` (default: ``InternalUnitSystem:UnitCurrent_in_cgs``),
-* a unit of temperature ``UnitTemp_in_cgs`` (default: ``InternalUnitSystem:UnitTemp_in_cgs``).
-
-When un-specified, these all take the same value as assumed by the internal
-system of units. These are rarely used but can offer a practical alternative to
-converting data in the post-processing of the simulations.
-
-For a standard cosmological run with structure finding activated, the
-full section would be:
-
-.. code:: YAML
-
- Snapshots:
- basename: output
- scale_factor_first: 0.02 # z = 49
- delta_time: 1.02
- invoke_stf: 1
-
-Showing all the parameters for a basic hydro test-case, one would have:
-
-.. code:: YAML
-
- Snapshots:
- basename: sedov
- time_first: 0.01
- delta_time: 0.005
- invoke_stf: 0
- int_time_label_on: 0
- compression: 3
- UnitLength_in_cgs: 1. # Use cm in outputs
- UnitMass_in_cgs: 1. # Use grams in outpus
- UnitVelocity_in_cgs: 1. # Use cm/s in outputs
- UnitCurrent_in_cgs: 1. # Use Ampere in outputs
- UnitTemp_in_cgs: 1. # Use Kelvin in outputs
-
-Some additional specific options for the snapshot outputs are described in the
-following pages:
-
-* :ref:`Output_list_label` (to have snapshots not evenly spaced in time),
-* :ref:`Output_selection_label` (to select what particle fields to write).
-
-
-.. _Parameters_statistics:
-
-Statistics
-----------
-
-Some additional specific options for the statistics outputs are described in the
-following page:
-
-* :ref:`Output_list_label` (to have statistics outputs not evenly spaced in time).
-
-.. _Parameters_restarts:
-
-Restarts
---------
-
-SWIFT can write check-pointing files and restart from them. The behaviour of
-this mechanism is driven by the options in the ``Restarts`` section of the YAML
-parameter file. All the parameters are optional but default to values that
-ensure a reasonable behaviour.
-
-* Whether 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``.
-
-* Whether or not to save a copy of the previous set of check-pointing files:
- ``save`` (default: ``1``),
-* Whether 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 basename
-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
-
-.. _Parameters_scheduler:
-
-Scheduler
----------
-
-.. _Parameters_domain_decomposition:
-
-Domain Decomposition
---------------------
-
-.. _Parameters_structure_finding:
-
-Structure finding (VELOCIraptor)
---------------------------------
-
-
-.. [#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 constant 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.
-
-.. [#f3] This feature only makes sense for non-cosmological runs for which the
- internal time unit is such that when rounded to the nearest integer a
- sensible number is obtained. A use-case for this feature would be to
- compare runs over the same physical time but with different numbers of
- snapshots. Snapshots at a given time would always have the same set of
- digits irrespective of the number of snapshots produced before.
-
diff --git a/doc/RTD/source/ParameterFiles/parameter_description.rst b/doc/RTD/source/ParameterFiles/parameter_description.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6304b60c5eb6df77d79e2ff50b9ba895d31a7889
--- /dev/null
+++ b/doc/RTD/source/ParameterFiles/parameter_description.rst
@@ -0,0 +1,634 @@
+.. Parameter Description
+ Matthieu Schaller, 21st October 2018
+
+.. _Parameters_basics:
+
+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
+
+ # Description 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 left unspecified 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``.
+
+.. _Parameters_units:
+
+Internal Unit System
+--------------------
+
+The ``InternalUnitSystem`` 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 the snapshots' ref:`ICs_units_label` section of the documentation)
+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 humorous `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]_.
+
+.. _Parameters_cosmology:
+
+Cosmology
+---------
+
+When running a cosmological simulation, the section ``Cosmology`` sets the values of the
+cosmological model. The expanded :math:`\Lambda\rm{CDM}` parameters governing the
+background evolution of the Universe 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 also 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 evolution 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`` run-time
+flag) this section of the YAML file is entirely ignored.
+
+.. _Parameters_gravity:
+
+Gravity
+-------
+
+The behaviour of the self-gravity solver can be modified by the parameters
+provided in the ``Gravity`` 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``.
+
+The 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 below 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 specified. 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
+
+
+.. _Parameters_SPH:
+
+SPH
+---
+
+.. _Parameters_time_integration:
+
+Time Integration
+----------------
+
+The ``TimeIntegration`` section is used to set some general parameters related to time
+integration. In all cases, users have to provide a minimal and maximal time-step
+size:
+
+* Maximal time-step size: ``dt_max``
+* Minimal time-step size: ``dt_min``
+
+These quantities are expressed in internal units. All particles will have their
+time-step limited by the maximal value on top of all the other criteria that may
+apply to them (gravity acceleration, Courant condition, etc.). If a particle
+demands a time-step size smaller than the minimum, SWIFT will abort with an
+error message. This is a safe-guard against simulations that would never
+complete due to the number of steps to run being too large.
+
+When running a non-cosmological simulation, the user also has to provide the
+time of the start and the time of the end of the simulation:
+
+* Start time: ``time_begin``
+* End time: ``time_end``
+
+Both are expressed in internal units. The start time is typically set to ``0``
+but SWIFT can handle any value here. For cosmological runs, these values are
+ignored and the start- and end-points of the runs are specified by the start and
+end scale-factors in the cosmology section of the parameter file.
+
+Additionally, when running a cosmological volume, advanced users can specify the
+value of the dimensionless pre-factor entering the time-step condition linked
+with the motion of particles with respect to the background expansion and mesh
+size. See the theory document for the exact equations.
+
+* Dimensionless pre-factor of the maximal allowed displacement:
+ ``max_dt_RMS_factor`` (default: ``0.25``)
+
+This value rarely needs altering.
+
+A full time-step section for a non-cosmological run would be:
+
+.. code:: YAML
+
+ TimeIntegration:
+ time_begin: 0 # Start time in internal units.
+ time_end: 10. # End time in internal units.
+ dt_max: 1e-2
+ dt_min: 1e-6
+
+Whilst for a cosmological run, one would need:
+
+.. code:: YAML
+
+ TimeIntegration:
+ dt_max: 1e-4
+ dt_min: 1e-10
+ max_dt_RMS_factor: 0.25 # Default optional value
+
+.. _Parameters_ICs:
+
+Initial Conditions
+------------------
+
+The ``InitialConditions`` 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
+
+
+.. _Parameters_constants:
+
+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.
+
+.. _Parameters_snapshots:
+
+Snapshots
+---------
+
+The ``Snapshots`` section of the parameter file contains all the options related to
+the dump of simulation outputs in the form of HDF5 :ref:`snapshots`. The main
+parameter is the base name that will be used for all the outputs in the run:
+
+* The base name of the HDF5 snapshots: ``basename``.
+
+This name will then be appended by an under-score and 4 digits followed by
+``.hdf5`` (e.g. ``base_name_1234.hdf5``). The 4 digits are used to label the
+different outputs, starting at ``0000``. In the default setup the digits simply
+increase by one for each snapshot. However, if the optional parameter
+``int_time_label_on`` is switched on, then we use 6 digits and these will the
+physical time of the simulation rounded to the nearest integer
+(e.g. ``base_name_001234.hdf5``) [#f3]_.
+
+The time of the first snapshot is controlled by the two following options:
+
+* Time of the first snapshot (non-cosmological runs): ``time_first``,
+* Scale-factor of the first snapshot (cosmological runs): ``scale_factor_first``.
+
+One of those two parameters has to be provided depending on the type of run. In
+the case of non-cosmological runs, the time of the first snapshot is expressed
+in the internal units of time. Users also have to provide the difference in time
+(or scale-factor) between consecutive outputs:
+
+* Time difference between consecutive outputs: ``delta_time``.
+
+In non-cosmological runs this is also expressed in internal units. For
+cosmological runs, this value is *multiplied* to obtain the
+scale-factor of the next snapshot. This implies that the outputs are
+equally space in :math:`\log(a)` (See :ref:`Output_list_label` to have
+snapshots not regularly spaced in time).
+
+When running the code with structure finding activated, it is often
+useful to have a structure catalog written at the same simulation time
+as the snapshots. To activate this, the following parameter can be
+switched on:
+
+* Run VELOCIraptor every time a snapshot is dumped: ``invoke_stf``
+ (default: ``0``).
+
+This produces catalogs using the options specified for the stand-alone
+VELOCIraptor outputs (see the section :ref:`Parameters_structure_finding`) but
+with a base name and output number that matches the snapshot name
+(e.g. ``stf_base_name_1234.hdf5``) irrespective of the name specified in the
+section dedicated to VELOCIraptor. Note that the invocation of VELOCIraptor at
+every dump is done additionally to the stand-alone dumps that can be specified
+in the corresponding section of the YAML parameter file.
+
+Users can optionally specify the level of compression used by the HDF5 library
+using the parameter:
+
+* GZIP compression level of the HDF5 arrays: ``compression`` (default: ``0``).
+
+The default level of ``0`` implies no compression and values have to be in the
+range :math:`[0-9]`. This integer is passed to the i/o library and used for the
+lossless GZIP compression algorithm. Higher values imply higher compression but
+also more time spent deflating and inflating the data. Note that up until HDF5
+1.10.x this option is not available when using the MPI-parallel version of the
+i/o routines.
+
+Finally, it is possible to specify a different system of units for the snapshots
+than the one that was used internally by SWIFT. The format is identical to the
+one described above (See the :ref:`Parameters_units` section) and read:
+
+* a unit of length: ``UnitLength_in_cgs`` (default: ``InternalUnitSystem:UnitLength_in_cgs``),
+* a unit of mass: ``UnitMass_in_cgs`` (default: ``InternalUnitSystem:UnitMass_in_cgs``),
+* a unit of velocity ``UnitVelocity_in_cgs`` (default: ``InternalUnitSystem:UnitVelocity_in_cgs``),
+* a unit of electric current ``UnitCurrent_in_cgs`` (default: ``InternalUnitSystem:UnitCurrent_in_cgs``),
+* a unit of temperature ``UnitTemp_in_cgs`` (default: ``InternalUnitSystem:UnitTemp_in_cgs``).
+
+When un-specified, these all take the same value as assumed by the internal
+system of units. These are rarely used but can offer a practical alternative to
+converting data in the post-processing of the simulations.
+
+For a standard cosmological run with structure finding activated, the
+full section would be:
+
+.. code:: YAML
+
+ Snapshots:
+ basename: output
+ scale_factor_first: 0.02 # z = 49
+ delta_time: 1.02
+ invoke_stf: 1
+
+Showing all the parameters for a basic hydro test-case, one would have:
+
+.. code:: YAML
+
+ Snapshots:
+ basename: sedov
+ time_first: 0.01
+ delta_time: 0.005
+ invoke_stf: 0
+ int_time_label_on: 0
+ compression: 3
+ UnitLength_in_cgs: 1. # Use cm in outputs
+ UnitMass_in_cgs: 1. # Use grams in outpus
+ UnitVelocity_in_cgs: 1. # Use cm/s in outputs
+ UnitCurrent_in_cgs: 1. # Use Ampere in outputs
+ UnitTemp_in_cgs: 1. # Use Kelvin in outputs
+
+Some additional specific options for the snapshot outputs are described in the
+following pages:
+
+* :ref:`Output_list_label` (to have snapshots not evenly spaced in time),
+* :ref:`Output_selection_label` (to select what particle fields to write).
+
+
+.. _Parameters_statistics:
+
+Statistics
+----------
+
+Some additional specific options for the statistics outputs are described in the
+following page:
+
+* :ref:`Output_list_label` (to have statistics outputs not evenly spaced in time).
+
+.. _Parameters_restarts:
+
+Restarts
+--------
+
+SWIFT can write check-pointing files and restart from them. The behaviour of
+this mechanism is driven by the options in the ``Restarts`` section of the YAML
+parameter file. All the parameters are optional but default to values that
+ensure a reasonable behaviour.
+
+* Whether 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``.
+
+* Whether or not to save a copy of the previous set of check-pointing files:
+ ``save`` (default: ``1``),
+* Whether 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 basename
+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
+
+.. _Parameters_scheduler:
+
+Scheduler
+---------
+
+.. _Parameters_domain_decomposition:
+
+Domain Decomposition
+--------------------
+
+.. _Parameters_structure_finding:
+
+Structure finding (VELOCIraptor)
+--------------------------------
+
+
+.. [#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 constant 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.
+
+.. [#f3] This feature only makes sense for non-cosmological runs for which the
+ internal time unit is such that when rounded to the nearest integer a
+ sensible number is obtained. A use-case for this feature would be to
+ compare runs over the same physical time but with different numbers of
+ snapshots. Snapshots at a given time would always have the same set of
+ digits irrespective of the number of snapshots produced before.
+
diff --git a/doc/RTD/source/conf.py b/doc/RTD/source/conf.py
index 46cff147efff3e7f23ff3f618898a17da3f85459..2249faa2851846c28e743400b2c826bfa6780c0a 100644
--- a/doc/RTD/source/conf.py
+++ b/doc/RTD/source/conf.py
@@ -87,7 +87,7 @@ html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
+# html_static_path = ['.static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.