Removed legacy sphinx modules

Removed some tags that were causing compilation issues

Moved old RTD around.

Added rtd-specific gitignore

Added 'new' RTD system

Added tempaltes of how to add new items to the documentation

Added HydroSchemes information

Added information from the onboarding guide into the online documentation, as well as adding the makefile

Add Equation of State documentation

Added the onboarding guide stuff

Added initial conditions section

Add eos documentation

Removed git marks

added minor change to the particle type table to make it fully consistent with SWIFT

Implemented Matthieu's changes

Updated information about minimalsph

removed statement about balsara switch

Add Cooling doc

Add cooling and update structure

Minor tidy up

Renamed section

doc/RTD/conf.py → doc/RTD-Legacy/conf.py

@@ -25,7 +25,7 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax']
+extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/RTD/.gitignore

+build/*
+make.bat

doc/RTD/Makefile

-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
-
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+SPHINXPROJ    = SWIFTSPHWIthFine-grainedinter-dependentTasking
+SOURCEDIR     = source
+BUILDDIR      = build
 
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SWIFT.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SWIFT.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/SWIFT"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SWIFT"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+.PHONY: help Makefile
 
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file

doc/RTD/README.md

+SWIFT Documentation
+===================
+
+This is the main documentation for SWIFT that can be found on ReadTheDocs.
+
+You will need the `sphinx` and `sphinx-autobuild` python packages (pip install
+them!) to build the documentation to html, as well as the `sphinx_rtd_theme`
+package which is used as the theme.
+
+To build the documentation, `make html` and then it is available in
+`build/html`.
+
+Please consider adding documentation when you add code!
+
+

doc/RTD/source/Cooling/index.rst

+.. Equation of State
+   Loic Hausammann, 7th April 2018
+
+.. _cooling:
+
+Cooling
+=======
+
+Currently, we have 5 different cooling (EAGLE, Grackle, const-lambda, const-du
+and none).  Three of them are easily solved analytically (const-lambda,
+const-du and none) while the two last requires complex chemical networks.
+
+
+Equations
+---------
+
+The first table compares the different analytical cooling while the next ones
+are specific to a given cooling.  The quantities are the internal energy (\\( u
+\\)), the density \\( rho \\), the element mass fraction (\\( X_i \\)), the
+cooling function (\\(\\Lambda\\), the proton mass (\\( m_H \\)) and the time
+step condition (\\( t\_\\text{step}\\)).  If not specified otherwise, all
+cooling contains a temperature floor avoiding negative temperature.
+
+.. csv-table:: Analytical Cooling
+   :header: "Variable", "Const-Lambda", "Const-du", "None"
+
+   "\\( \\frac{ \\mathrm{d}u }{ \\mathrm{d}t } \\)", "\\( -\\Lambda \\frac{\\rho^2 X_H^2}{\\rho m_H^2} \\)", "const", "0"
+   "\\( \\Delta t\_\\text{max} \\)", "\\( t\_\\text{step} \\frac{u}{\\left|\\frac{ \\mathrm{d}u }{ \\mathrm{d}t }\\right|} \\)", "\\( t\_\\text{step} \\frac{u}{\\ \\left| \\frac{ \\mathrm{d}u }{ \\mathrm{d}t }\\right|} \\)", "None"
+
+
+Grackle
+~~~~~~~
+   
+Grackle is a chemistry and cooling library presented in B. Smith et al. 2016
+(do not forget to cite if used).  Four different modes are available:
+equilibrium, 6 species network (H, H\\( ^+ \\), e\\( ^- \\), He, He\\( ^+ \\)
+and He\\( ^{++} \\)), 9 species network (adds H\\(^-\\), H\\(_2\\) and
+H\\(_2^+\\)) and 12 species (adds D, D\\(^+\\) and HD).  Following the same
+order, the swift cooling options are ``grackle``, ``grackle1``, ``grackle2``
+and ``grackle3`` (the numbers correspond to the value of
+``primordial_chemistry`` in Grackle).  It also includes some self-shielding
+methods and UV background.  In order to use the Grackle cooling, you will need
+to provide an HDF5 table computed by Cloudy.
+
+When starting a simulation without providing the different fractions, the code
+supposes an equilibrium and computes the fractions automatically.
+
+Eagle
+~~~~~
+
+TODO
+
+How to Implement a New Cooling
+------------------------------
+
+The developper should provide at least one function for:
+ * writing the cooling name in HDF5
+ * cooling a particle
+ * the maximal time step possible
+ * initializing a particle
+ * computing the total energy radiated by a particle
+ * initializing the cooling parameters
+ * printing the cooling type
+
+For implementation details, see ``src/cooling/none/cooling.h``
+
+See :ref:`new_option` for the full list of changes required.

doc/RTD/source/EquationOfState/index.rst

+.. Equation of State
+   Loic Hausammann, 6th April 2018
+
+.. _equation_of_state:
+
+Equation of State
+=================
+
+Currently (if the documentation was well updated), we have two different
+equation of states implemented: ideal gas and isothermal.  They describe the
+relations between our main thermodynamical variables: the internal energy
+(\\(u\\)), the density (\\(\\rho\\)), the entropy (\\(A\\)) and the pressure
+(\\(P\\)).
+
+Equations
+---------
+
+In the following section, the variables not yet defined are: \\(\\gamma\\) for
+the adiabatic index and \\( c_s \\) for the speed of sound.
+
+.. csv-table:: Ideal Gas
+   :header: "Variable", "A", "u", "P"
+	   
+   "A", "", "\\( \\left( \\gamma - 1 \\right) u \\rho^{1-\\gamma} \\)", "\\(P \\rho^{-\\gamma} \\)"
+   "u", "\\( A \\frac{ \\rho^{ \\gamma - 1 } }{\\gamma - 1 } \\)", "", "\\(\\frac{1}{\\gamma - 1} \\frac{P}{\\rho}\\)"
+   "P", "\\( A \\rho^\\gamma \\)", "\\( \\left( \\gamma - 1\\right) u \\rho \\)", ""
+   "\\(c_s\\)", "\\(\\sqrt{ \\gamma \\rho^{\\gamma - 1} A}\\)", "\\(\\sqrt{ u \\gamma \\left( \\gamma - 1 \\right) } \\)", "\\(\\sqrt{ \\frac{\\gamma P}{\\rho} }\\)"
+
+
+.. csv-table:: Isothermal Gas
+   :header: "Variable", "A", "u", "P"
+
+	    
+   "A", "", "\\(\\left( \\gamma - 1 \\right) u \\rho^{1-\\gamma}\\)", "" 
+   "u", "", "const", ""
+   "P", "", "\\(\\left( \\gamma - 1\\right) u \\rho \\)", ""
+   "\\( c_s\\)", "", "\\(\\sqrt{ u \\gamma \\left( \\gamma - 1 \\right) } \\)", ""
+
+
+How to Implement a New Equation of State
+----------------------------------------
+
+See :ref:`new_option` for a full list of required changes.
+
+You will need to provide a ``equation_of_state.h`` file containing: the
+definition of ``eos_parameters``, IO functions and transformations between the
+different variables: \\(u(\\rho, A)\\), \\(u(\\rho, P)\\), \\(P(\\rho,A)\\),
+\\(P(\\rho, u)\\), \\(A(\\rho, P)\\), \\(A(\\rho, u)\\), \\(c_s(\\rho, A)\\),
+\\(c_s(\\rho, u)\\) and \\(c_s(\\rho, P)\\). See other equation of state files
+to have implementation details.

doc/RTD/source/GettingStarted/compiling_code.rst

+.. Compiling the Code
+   Josh Borrow, 5th April 2018
+
+
+Compiling SWIFT
+===============
+
+Dependencies
+------------
+
+To compile SWIFT, you will need the following libraries:
+
+HDF5
+~~~~
+
+Version 1.8.x or higher is required. Input and output files are stored as HDF5
+and are compatible with the existing GADGET-2 specification. Please consider
+using a build of parallel-HDF5, as SWIFT can leverage this when writing and
+reading snapshots. We recommend using HDF5 > 1.10.x as this is `vastly superior`
+in parallel.
+
+MPI
+~~~
+A recent implementation of MPI, such as Open MPI (v2.x or higher), is required,
+or any library that implements at least the MPI 3 standard.
+
+Libtool
+~~~~~~~
+The build system depends on libtool.
+
+FFTW
+~~~~
+Version 3.3.x or higher is required for periodic gravity.
+
+METIS
+~~~~~
+METIS is used for domain decomposition and load balancing.
+
+libNUMA
+~~~~~~~
+libNUMA is used to pin threads.
+
+GSL
+~~~
+The GSL is required for cosmological integration.
+
+
+Optional Dependencies
+---------------------
+
+There are also the following _optional_ dependencies.
+
+TCmalloc/Jemalloc
+~~~~~~~~~~~~~~~~~
+TCmalloc/Jemalloc are used for faster memory allocations when available.
+
+DOXYGEN
+~~~~~~~
+You can build documentation for SWIFT with DOXYGEN.
+
+Python
+~~~~~~
+To run the examples, you will need python and some of the standard scientific libraries (numpy, matplotlib). Some examples use Python 2 scripts, but the more recent ones use Python 3 (this is specified in individual READMEs).
+
+GRACKLE
+~~~~~~~
+GRACKLE cooling is implemented in SWIFT. If you wish to take advantage of it, you will need it installed.
+
+
+Initial Setup
+-------------
+
+We use autotools for setup. To get a basic running version of the code
+(the binary is created in swiftsim/examples) on most platforms, run
+
+.. code-block:: bash
+
+  ./autogen.sh
+  ./configure
+  make
+
+
+MacOS Specific Oddities
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To build on MacOS you will need to disable compiler warnings due to an
+incomplete implementation of pthread barriers. DOXYGEN also has some issues on
+MacOS, so it is best to leave it out. To configure:
+
+.. code-block:: bash
+
+  ./configure —disable-compiler-warnings —disable-doxygen-doc
+

doc/RTD/source/GettingStarted/configuration_options.rst

+.. Configuration Options
+   Josh Borrow, 5th April 2018
+
+Configuration Options
+=====================
+
+There are many configuration options that SWIFT makes available; a few key
+ones are summarised here.
+
+Note that these need to be ran with ``./configure x`` where ``x`` is the
+configuration flag.
+
+A description of the available options of the below flags can be found by using
+``./configure  --help``.
+
+``--with-hydro=gadget2``
+~~~~~~~~~~~~~~~~~~~~~~~~
+There are several hydrodynamical schemes available in SWIFT. You can choose
+between them at compile-time with this option.
+
+``--with-riemann-solver=none``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Some hydrodynamical schemes, for example GIZMO, require a Riemann solver.
+
+``--with-kernel=cubic-spline``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Several kernels are made available for use with the hydrodynamical schemes.
+Choose between them with this compile-time flag.
+
+``--with-hydro-dimension=3``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Run problems in 1, 2, and 3 (default) dimensions.
+
+``--with-equation-of-state=ideal-gas``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Several equations of state are made available with this flag. Also consider
+``--with-adiabatic-index``.
+
+``--with-cooling=none``
+~~~~~~~~~~~~~~~~~~~~~~~
+Several cooling implementations (including GRACKLE) are available.
+
+``--with-ext-potential=none``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Many external potentials are available for use with SWIFT. You can choose
+between them at compile time. Some examples include a central potential, a
+softened central potential, and a sinusoidal potential. You will need to
+configure, for example, the mass in your parameterfile at runtime.
+
+

doc/RTD/source/GettingStarted/index.rst

+.. Getting Started
+   Josh Borrow, 4th April 2018
+
+Getting Started
+===============
+
+So, you want to use SWIFT? Below you should find all of the information you need
+to get up and running with some examples, and then build your own initial conditions
+for running.
+
+Also, you might want to consult our onboarding guide (available at
+http://www.swiftsim.com/onboarding.pdf) if you would like something to print out
+and keep on your desk.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   compiling_code
+   running_example
+   runtime_options
+   configuration_options
+   what_about_mpi

doc/RTD/source/GettingStarted/running_example.rst

+.. Running an Example
+   Josh Borrow, 5th April 2018
+
+Running an Example
+==================
+
+Now that you have built the code, you will want to run an example! To do that,
+you need to follow the following instructions (requires ``python2`` or
+``python3`` with the ``h5py`` and other standard scientific packages, as well
+as ``wget`` for grabbing the glass).
+
+.. code-block:: bash
+   
+   cd examples/SodShock_3D
+   ./getGlass.sh
+   python makeIC.py
+   ../swift -s -t 4 sodShock.yml
+   python plotSolution.py 1
+
+
+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
+_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-riemann-solver=hllc
+
+
+To see the results that you should get, you should check out our developer
+wiki at https://gitlab.cosma.dur.ac.uk/swift/swiftsim/wikis/Sod_3D.
+
+If you don't get these results, please contact us on our GitHub page at
+https://github.com/SWIFTSIM/swiftsim/issues.

doc/RTD/source/GettingStarted/runtime_options.rst

+.. Runtime Options
+   Josh Borrow, 5th April 2018
+
+Runtime 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 runtime 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.
++ ``-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/GettingStarted/what_about_mpi.rst

+.. What about MPI? Running SWIFT on more than one node
+   Josh Borrow, 5th April 2018
+
+What about MPI? Running SWIFT on more than one node
+===================================================
+
+After compilation, you will be left with two binaries. One is called ``swift``,
+and the other ``swift_mpi``. Current wisdom is to run ``swift`` if you are only
+using one node (i.e. without any interconnect), and one MPI rank per NUMA
+region using ``swift_mpi`` for anything larger. You will need some GADGET-2
+HDF5 initial conditions to run SWIFT, as well as a compatible yaml
+parameterfile.

doc/RTD/source/HydroSchemes/adding_your_own.rst

+.. Adding Hydro Schemes
+   Josh Borrow, 5th April 2018
+
+
+Adding Hydro Schemes
+====================
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Contents:
+
+SWIFT is engineered to enable you to add your own hydrodynamics schemes easily.
+We enable this through the use of header files to encapsulate each scheme.
+
+Note that it's unlikely you will ever have to consider paralellism or 'loops over
+neighbours' for SWIFT; all of this is handled by the tasking system. All we ask
+for is the interaction functions that tell us how to a) compute the density
+and b) compute forces.
+
+
+Getting Started
+---------------
+
+The hydro schemes are stored in ``src/hydro``. You will need to create a folder
+with a sensible name that you are going to store your scheme-specific information
+in. Then, you will need to create the following files:
+
++ ``hydro.h``, which includes functions that are applied to particles at the end
+  of the density loop and beginning of the force loop, along with helper functions
++ ``hydro_debug.h``, which includes a quick function that prints out your particle
+  properties for debugging purposes
++ ``hydro_iact.h`` that includes the interaction functions
++ ``hydro_io.h`` which includes the information on what should be read from the
+  initial conditions file, as well as written to the output files
++ ``hydro_part.h`` which includes your particle definition. SWIFT uses an array-of
+  -structures scheme.
+
+
+``hydro.h``
+-----------
+
+As previously noted, ``hydro.h`` includes the helper functions for your scheme. You
+will need to 'fill out' the following:
+
++ ``hydro_get_comoving_internal_energy(p)`` which returns the comoving internal energy
+  of your particles (typically this will just be ``p->u``).
++ ``hydro_get_physical_internal_energy(p, cosmo)`` which returns the physical internal
+  energy. You can use the ``a_factor_internal_energy`` from the ``cosmology`` struct.
++ ``hydro_get_comoving_pressure(p)`` which returns the comoving pressure.
++ ``hydro_get_comoving_entropy(p)`` which returns the comoving entropy.
++ ``hydro_get_physical_entropy(p, cosmo)`` which returns the physical entropy. In our
+  formalism, usually there is no conversion factor here so it is the same as the
+  comoving version.
++ ``hydro_get_comoving_soundspeed(p)`` which returns the comoving sound speed.
++ ``hydro_get_physical_soundspeed(p, cosmo)`` which returns the physical sound
+  speed. You can use the ``a_factor_sound_speed``.
++ ``hydro_get_comoving_density(p)`` which returns the comoving density.
++ ``hydro_get_physical_density(p, cosmo)`` which returns the physical density.
+  You can use the ``a3_inv`` member of the ``cosmology`` struct.
++ ``hydro_get_mass(p)`` returns the mass of particle ``p``.
++ ``hydro_get_drifted_velocities(p, xp, dt_kick_hydro, dt_kick_grav, v[3])`` gets
+  the drifted velocities; this is just ``a_hydro * dt_kick_hydro`` + ``a_grav *
+  dt_kick_grav`` in most implementations.
++ ``hydro_get_energy_dt(p)`` returns the time derivative of the (comoving) internal
+  energy of the particle.
++ ``hydro_set_energy_dt(p)`` sets the time derivative of the (comoving) internal
+  energy of the particle.
++ ``hydro_compute_timestep(p, xp, hydro_props, cosmo)`` returns the timestep for 
+  the hydrodynamics particles.
++ ``hydro_timestep_extra(p, dt)`` does some extra hydro operations once the
+  physical timestel for the particle is known.
++ ``hydro_init_part(p, hydro_space)`` initialises the particle in preparation for
+  the density calculation. This essentially sets properties, such as the density,
+  to zero.
++ ``hydro_end_density(p, cosmo)`` performs operations directly after the density
+  loop on each particle. Note that you will have to add a particle's self-contribution
+  at this stage as particles are never 'interacted' with themselves.
++ ``hydro_part_has_no_neighbours(p, xp, cosmo)`` resets properties to a sensible
+  value if a particle is found to have no neighbours.
++ ``hydro_prepare_force(p, xp, cosmo)`` is computed for each particle before the
+  force loop. You can use this to pre-compute particle properties that are used
+  in the force loop, but only depend on the particle itself.
++ ``hydro_reset_acceleration(p)`` resets the acceleration variables of the particles
+  to zero in preparation for the force loop.
++ ``hydro_predict_extra(p, xp, dt_drift, dt_therm)`` predicts extra particle properties
+  when drifting, such as the smoothing length.
++ ``hydro_end_force(p, cosmo)`` is called after the force loop for each particle and 
+  can be used to e.g. include overall factors of the smoothing length.
++ ``hydro_kick_extra(p, xp, dt_therm)`` kicks extra variables.
++ ``hydro_convert_quantities(p, xp)`` converts quantities at the start of a run (e.g.
+  internal energy to entropy).
++ ``hydro_first_init_part(p, xp)`` is called for every particle at the start of a run
+  and is used to initialise variables.
+
+
+``hydro_debug.h``
+-----------------
+
+TBD
+
+
+``hydro_iact.h``
+----------------
+
+TBD
+
+
+``hydro_io.h``
+--------------
+
+TBD
+
+
+``hydro_part.h``
+----------------
+
+TBD
+

doc/RTD/source/HydroSchemes/gizmo.rst

+.. GIZMO (MFV)
+   Josh Borrow, 5th April 2018
+
+GIZMO-Like Scheme
+=================
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Contents:
+
+
+There is a meshless finite volume (MFV) GIZMO-like scheme implemented in SWIFT
+(see Hopkins 2015 for more information). You will need a Riemann solver to run
+this, and configure as follows:
+
+.. code-block:: bash
+   
+   ./configure --with-hydro="gizmo" --with-riemann-solver="hllc" --disable-vec
+

doc/RTD/source/HydroSchemes/hopkins_sph.rst

+.. 'Hopkins'-SPH
+   Josh Borrow 5th April 2018
+
+Pressure-Entropy SPH
+====================
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Contents:
+
+A pressure-entropy SPH scheme is available in SWIFT, inspired by Hopkins 2013.
+This includes a Monaghan AV scheme and a Balsara switch.
+
+
+.. code-block:: bash
+   
+   ./configure --with-hydro="hopkins"
+
+
+Pressure-Energy SPH
+===================
+
+A pressure-energy SPH scheme is currently being implemented in SWIFT.