From 0c5696fba72fceeaf9005faf5ed84b480e78cbbb Mon Sep 17 00:00:00 2001
From: Jacob Kegerreis <jacob.kegerreis@durham.ac.uk>
Date: Fri, 13 Mar 2020 14:57:12 +0000
Subject: [PATCH] Consolidate the planetary info
---
doc/RTD/source/EquationOfState/index.rst | 43 ++----------------
doc/RTD/source/HydroSchemes/planetary_sph.rst | 19 +-------
.../source/Planetary/equations_of_state.rst | 45 +++++++++++++++++++
doc/RTD/source/Planetary/hydro_scheme.rst | 17 +++++++
doc/RTD/source/Planetary/index.rst | 8 +++-
5 files changed, 73 insertions(+), 59 deletions(-)
create mode 100644 doc/RTD/source/Planetary/equations_of_state.rst
create mode 100644 doc/RTD/source/Planetary/hydro_scheme.rst
diff --git a/doc/RTD/source/EquationOfState/index.rst b/doc/RTD/source/EquationOfState/index.rst
index 187246112c..509497a489 100644
--- a/doc/RTD/source/EquationOfState/index.rst
+++ b/doc/RTD/source/EquationOfState/index.rst
@@ -51,49 +51,12 @@ formulation) written to the snapshots is meaningless. The pressure,
however, is always correct in all scheme.
-.. _planetary_equation_of_state:
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): 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.
-
-See :ref:`planetary` for other related information.
+
+See :ref:`planetary_eos`.
+
How to Implement a New Equation of State
diff --git a/doc/RTD/source/HydroSchemes/planetary_sph.rst b/doc/RTD/source/HydroSchemes/planetary_sph.rst
index cd8debfaec..798c4ecd2d 100644
--- a/doc/RTD/source/HydroSchemes/planetary_sph.rst
+++ b/doc/RTD/source/HydroSchemes/planetary_sph.rst
@@ -11,21 +11,4 @@ Planetary (Density-Energy, Multi-Material) SPH
:hidden:
:caption: Contents:
-This scheme is based on the :ref:`minimal` scheme but also allows multiple
-materials, meaning that different SPH particles can be assigned different
-:ref:`equation_of_state` (EoS).
-
-The Balsara viscosity switch is also used, but can be disabled by
-compiling SWIFT with ``make CFLAGS=-DPLANETARY_SPH_NO_BALSARA``.
-
-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.
-
-See :ref:`planetary` for other related information.
+See :ref:`planetary_hydro`.
diff --git a/doc/RTD/source/Planetary/equations_of_state.rst b/doc/RTD/source/Planetary/equations_of_state.rst
new file mode 100644
index 0000000000..63ad1a6cfb
--- /dev/null
+++ b/doc/RTD/source/Planetary/equations_of_state.rst
@@ -0,0 +1,45 @@
+.. 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.
diff --git a/doc/RTD/source/Planetary/hydro_scheme.rst b/doc/RTD/source/Planetary/hydro_scheme.rst
new file mode 100644
index 0000000000..ae920722c1
--- /dev/null
+++ b/doc/RTD/source/Planetary/hydro_scheme.rst
@@ -0,0 +1,17 @@
+.. 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``.
diff --git a/doc/RTD/source/Planetary/index.rst b/doc/RTD/source/Planetary/index.rst
index c083dde919..c7e9be3db2 100644
--- a/doc/RTD/source/Planetary/index.rst
+++ b/doc/RTD/source/Planetary/index.rst
@@ -25,4 +25,10 @@ SWIFT configured to use the planetary hydrodynamics scheme and equations of stat
``--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!).
-See :ref:`planetary_sph` and :ref:`planetary_equation_of_state` for more details.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: More information:
+
+ Hydro Scheme <hydro_scheme>
+ Equations of State <equations_of_state>
--
GitLab