Merge branch 'planetary_docs' into 'master'

Planetary documentation

Closes #659

See merge request !1038

doc/RTD/source/EquationOfState/index.rst

 .. Equations of State
    Loic Hausammann, 6th April 2018
-   Jacob Kegerreis, 3rd February 2019
+   Jacob Kegerreis, 13th March 2020
 
 .. _equation_of_state:
 
@@ -50,46 +50,13 @@ density-entropy scheme or the internal enegy in a density-energy SPH
 formulation) written to the snapshots is meaningless. The pressure,
 however, is always correct in all scheme.
 
+
+
 Planetary EoS
 -------------
-Configuring SWIFT with the ``--with-equation-of-state=planetary`` and 
-``--with-hydro=planetary`` options enables the use of multiple EoS.
-Every SPH particle then requires and carries the additional ``MaterialID`` flag 
-from the initial conditions file. This flag indicates the particle's material 
-and which EoS it should use. 
-
-So far, we have implemented several Tillotson, SESAME, and Hubbard \& MacFarlane 
-(1980) materials, with more on their way.
-The material's ID is set by a base type ID (multiplied by 100), plus a minor 
-type:
-
-+ Tillotson (Melosh, 2007): ``1``
-    + Iron: ``100``
-    + Granite: ``101``
-    + Water: ``102``
-+ Hubbard \& MacFarlane (1980): ``2``
-    + Hydrogen-helium atmosphere: ``200``
-    + Ice H20-CH4-NH3 mix: ``201``
-    + Rock SiO2-MgO-FeS-FeO mix: ``202``
-+ SESAME (and similar): ``3``
-    + Iron (2140): ``300``
-    + Basalt (7530): ``301``
-    + Water (7154): ``302``
-    + Senft \& Stewart (2008) water (in a SESAME-style table): ``303``
-
-Unlike the EoS for an ideal or isothermal gas, these more complicated materials 
-do not always include transformations between the internal energy, 
-temperature, and entropy. At the moment, we have only implemented 
-\\(P(\\rho, u)\\) and \\(c_s(\\rho, u)\\). 
-This is sufficient for the simple :ref:`planetary_sph` hydrodynamics scheme, 
-but makes these materials currently incompatible with other entropy-based 
-schemes.
-
-The Tillotson sound speed was derived using 
-\\(c_s^2 = \\left. \\dfrac{\\partial P}{\\partial \\rho} \\right|_S \\)
-as described in Kegerreis et al. (2019).
-The table files for the HM80 and SESAME-style EoS can be downloaded using 
-the ``examples/EoSTables/get_eos_tables.sh`` script.
+
+See :ref:`planetary_eos`.
+
 
 
 How to Implement a New Equation of State

doc/RTD/source/HydroSchemes/index.rst

@@ -15,7 +15,7 @@ schemes available in SWIFT, as well as how to implement your own.
 
    traditional_sph
    minimal_sph
-   planetary
+   planetary_sph
    hopkins_sph
    anarchy_sph
    sphenix_sph

doc/RTD/source/HydroSchemes/minimal_sph.rst

 .. Minimal SPH
    Josh Borrow 4th April 2018
 
+.. _minimal:
+
 Minimal (Density-Energy) SPH
 ============================
 

doc/RTD/source/HydroSchemes/planetary.rst

-.. Planetary SPH
-    Jacob Kegerreis, 3rd February 2019
-
-.. _planetary_sph:
-
-Planetary (Density-Energy, Multi-Material) SPH
-==============================================
-
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: Contents:
-
-This scheme is the same as the Minimal SPH scheme but also allows multiple 
-materials, meaning that different SPH particles can be assigned different 
-:ref:`equation_of_state` (EoS).
-
-To use the planetary scheme and the corresponding planetary EoS, use 
-
-.. code-block:: bash
-
-    ./configure --with-hydro=planetary --with-equation-of-state=planetary
-
-Every SPH particle then requires and carries the additional ``MaterialID`` flag 
-from the initial conditions file. This flag indicates the particle's material 
-and which EoS it should use. 
\ No newline at end of file

doc/RTD/source/HydroSchemes/planetary_sph.rst

+.. Planetary SPH
+    Jacob Kegerreis, 13th March 2020
+
+.. _planetary_sph:
+
+Planetary (Density-Energy, Multi-Material) SPH
+==============================================
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Contents:
+
+See :ref:`planetary_hydro`.

doc/RTD/source/Planetary/equations_of_state.rst

+.. Planetary EoS
+    Jacob Kegerreis, 13th March 2020
+
+.. _planetary_eos:
+
+Planetary Equations of State
+============================
+   
+Configuring SWIFT with the ``--with-equation-of-state=planetary`` and 
+``--with-hydro=planetary`` options enables the use of multiple EoS.
+Every SPH particle then requires and carries the additional ``MaterialID`` flag 
+from the initial conditions file. This flag indicates the particle's material 
+and which EoS it should use. 
+
+So far, we have implemented several Tillotson, SESAME, and Hubbard \& MacFarlane 
+(1980) materials, with more on their way.
+The material's ID is set by a base type ID (multiplied by 100), plus a minor 
+type:
+
++ Tillotson (Melosh, 2007): Base type ``1``
+    + Iron: ``100``
+    + Granite: ``101``
+    + Water: ``102``
++ Hubbard \& MacFarlane (1980): Base type ``2``
+    + Hydrogen-helium atmosphere: ``200``
+    + Ice H20-CH4-NH3 mix: ``201``
+    + Rock SiO2-MgO-FeS-FeO mix: ``202``
++ SESAME (and similar): Base type ``3``
+    + Iron (2140): ``300``
+    + Basalt (7530): ``301``
+    + Water (7154): ``302``
+    + Senft \& Stewart (2008) water (in a SESAME-style table): ``303``
+
+Unlike the EoS for an ideal or isothermal gas, these more complicated materials 
+do not always include transformations between the internal energy, 
+temperature, and entropy. At the moment, we have only implemented 
+\\(P(\\rho, u)\\) and \\(c_s(\\rho, u)\\). 
+This is sufficient for the simple :ref:`planetary_sph` hydrodynamics scheme, 
+but makes these materials currently incompatible with entropy-based schemes.
+
+The Tillotson sound speed was derived using 
+\\(c_s^2 = \\left. \\dfrac{\\partial P}{\\partial \\rho} \\right|_S \\)
+as described in `Kegerreis et al. (2019) <https://doi.org/10.1093/mnras/stz1606>`_.
+The table files for the HM80 and SESAME-style EoS can be downloaded using 
+the ``swiftsim/examples/EoSTables/get_eos_tables.sh`` script.

doc/RTD/source/Planetary/hydro_scheme.rst

+.. Planetary SPH
+    Jacob Kegerreis, 13th March 2020
+
+.. _planetary_hydro:
+
+Planetary Hydro Scheme
+======================
+
+This scheme is based on :ref:`minimal` but also allows multiple materials, 
+meaning that different SPH particles can be assigned different 
+`equations of state <equations_of_state.html>`_ (EoS). 
+Every SPH particle then requires and carries the additional ``MaterialID`` flag 
+from the initial conditions file. This flag indicates the particle's material 
+and which EoS it should use. 
+
+The Balsara viscosity switch is used by default, but can be disabled by 
+compiling SWIFT with ``make CFLAGS=-DPLANETARY_SPH_NO_BALSARA``.

doc/RTD/source/Planetary/index.rst

+.. Planetary Simulations
+   Jacob Kegerreis, 13th March 2020
+
+.. _planetary:
+   
+Planetary Simulations
+=====================
+
+SWIFT is also designed for running planetary simulations
+with a focus on giant impacts, as presented in 
+`Kegerreis et al. (2019) <https://doi.org/10.1093/mnras/stz1606>`_, MNRAS 487:4.
+
+New features for planetary simulations are in active development
+so please let us know if you are interested in using SWIFT 
+or have any implementation requests. For example a new equation of state
+or extensions to the tools for creating initial conditions.
+    
+You can find an example simulation in ``swiftsim/examples/Planetary/``
+under ``EarthImpact/``.
+The tabulated equations of state files can be downloaded using 
+``EoSTables/get_eos_tables.sh``.
+
+Planetary simulations are currently intended to be run with 
+SWIFT configured to use the planetary hydrodynamics scheme and equations of state:
+``--with-hydro=planetary`` and ``--with-equation-of-state=planetary``.
+These allow for multiple materials to be used,
+chosen from the several available equations of state (more coming soon!).
+
+.. toctree::
+   :maxdepth: 2
+   :caption: More information:
+   
+   Hydro Scheme <hydro_scheme>
+   Equations of State <equations_of_state>

doc/RTD/source/index.rst

@@ -23,6 +23,7 @@ difference is the parameter file that will need to be adapted for SWIFT.
    TimeStepping/index
    SubgridModels/index
    random
+   Planetary/index
    FriendsOfFriends/index
    EquationOfState/index
    ExternalPotentials/index