Add barotropic EoS

Add barotropic EoS that is used in some MHD problems.

Todo:

• Add reference to the paper where this is taken from,
• Fix the few equations labelled as "IS THIS CORRECT",
• Fix the Doxygen comments to have the correct equations.
• Fix the example/parameter_examples.yml file to have a description of the two parameters.

doc/RTD/source/EquationOfState/index.rst

@@ -7,20 +7,20 @@
 Equations of State
 ==================
 
-Currently, SWIFT offers two different gas equations of state (EoS)
-implemented: ``ideal`` and ``isothermal``; as well as a variety of EoS for
-"planetary" materials.  The EoS describe the relations between our
-main thermodynamical variables: the internal energy per unit mass
-(\\(u\\)), the mass density (\\(\\rho\\)), the entropy (\\(A\\)) and
-the pressure (\\(P\\)).
+Currently, SWIFT offers three different gas equations of state (EoS)
+implemented: ``ideal``, ``isothermal``, and ``barotropic``; as well as a variety
+of EoS for "planetary" materials.  The EoS describe the relations between our
+main thermodynamical variables: the internal energy per unit mass :math:`u`, the
+mass density :math:`\rho`, the entropy :math:`A` and the pressure :math:`P`.
+It is selected af configure time via the option ``--with-equation-of-state``.
 
 Gas EoS
 -------
 
-We write the adiabatic index as \\(\\gamma \\) and \\( c_s \\) denotes
+We write the adiabatic index as :math:`\gamma` and :math:`c_s` denotes
 the speed of sound. The adiabatic index can be changed at configure
 time by choosing one of the allowed values of the option
-``--with-adiabatic-index``. The default value is \\(\\gamma = 5/3 \\).
+``--with-adiabatic-index``. The default value is :math:`\gamma = 5/3`.
 
 The tables below give the expression for the thermodynamic quantities
 on each row entry as a function of the gas density and the
@@ -29,27 +29,38 @@ thermodynamical quantity given in the header of each column.
 .. 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} }\\)"
+   "A", "", :math:`\left( \gamma - 1 \right) u \rho^{1-\gamma}`, :math:`P \rho^{-\gamma}`
+   "u", :math:`A \frac{ \rho^{ \gamma - 1 } }{\gamma - 1 }`, "", :math:`\frac{1}{\gamma - 1} \frac{P}{\rho}`
+   "P", :math:`A \rho^\gamma`, :math:`\left( \gamma - 1\right) u \rho`, ""
+   :math:`c_s`, :math:`\sqrt{ \gamma \rho^{\gamma - 1} A}`, :math:`\sqrt{ u \gamma \left( \gamma - 1 \right) }`, :math:`\sqrt{ \frac{\gamma P}{\rho} }`
 
 
 .. csv-table:: Isothermal Gas
-   :header: "Variable", "A", "u", "P"
+   :header: "Variable", "-", "-", "-"
 
 	    
-   "A", "", "\\(\\left( \\gamma - 1 \\right) u \\rho^{1-\\gamma}\\)", "" 
+   "A", "", :math:`\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) } \\)", ""
-
-Note that when running with an isothermal equation of state, the value
-of the tracked thermodynamic variable (e.g. the entropy in a
+   "P", "", :math:`\left( \gamma - 1\right) u \rho`, ""
+   :math:`c_s`, "", :math:`\sqrt{ u \gamma \left( \gamma - 1 \right) }`, ""
+
+.. csv-table:: Barotropic Gas
+   :header: "Variable", "-", "-", "-"
+
+   "A", "", :math:`\rho^{1-\gamma} c_0^2 \sqrt{1 + \left( \frac{\rho}{\rho_c}  \right) }`, ""
+   "u", "", :math:`\frac{1}(\gamma -1)c_0^2 \sqrt{1 + \left( \frac{\rho}{\rho_c}  \right) }`, ""
+   "P", "", :math:`\rho c_0^2 \sqrt{1 + \left( \frac{\rho}{\rho_c}  \right) }`, ""
+   :math:`c_s`, "", :math:`\sqrt{ c_0^2 \sqrt{1 + \left( \frac{\rho}{\rho_c}  \right) }}`, ""
+   
+Note that when running with an isothermal or barotropic equation of state, the
+value of the tracked thermodynamic variable (e.g. the entropy in a
 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.
+formulation) written to the snapshots is meaningless. The pressure, however, is
+always correct in all scheme.
 
+For the isothermal equation of state, the internal energy is specified at
+runtime via the parameter file. In the case of the barotropic gas, the vacuum
+sound speed :math:`c_0` and core density :math:`\rho_c` are similarly specified.
 
 
 Planetary EoS
@@ -66,7 +77,7 @@ See :ref:`new_option` for a full list of required changes.
 
 You will need to provide an ``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
+different variables: :math:`u(\rho, A)`, :math:`u(\rho, P)`, :math:`P(\rho,A)`,
+:math:`P(\rho, u)`, :math:`A(\rho, P)`, :math:`A(\rho, u)`, :math:`c_s(\rho, A)`,
+:math:`c_s(\rho, u)` and :math:`c_s(\rho, P)`. See other equation of state files
 to have implementation details.