From 28f3218aa87c8e8929d032b75f60222bb96c8958 Mon Sep 17 00:00:00 2001
From: Bob Myhill <myhill.bob@gmail.com>
Date: Mon, 25 Nov 2024 11:02:43 +0000
Subject: [PATCH] improve docstrings

---
 burnman/eos/birch_murnaghan_4th.py | 37 ++++++++++++++++++++++--------
 burnman/eos/modified_tait.py       | 22 +++++++++++-------
 2 files changed, 42 insertions(+), 17 deletions(-)

diff --git a/burnman/eos/birch_murnaghan_4th.py b/burnman/eos/birch_murnaghan_4th.py
index 52815b28..8ba753e2 100644
--- a/burnman/eos/birch_murnaghan_4th.py
+++ b/burnman/eos/birch_murnaghan_4th.py
@@ -19,8 +19,8 @@ def bulk_modulus_fourth(volume, params):
     modulus.  Pressure must be in :math:`[Pa]`.
     """
 
-    x = params["V_0"] / volume
-    f = 0.5 * (pow(x, 2.0 / 3.0) - 1.0)
+    invVrel = params["V_0"] / volume
+    f = 0.5 * (pow(invVrel, 2.0 / 3.0) - 1.0)
 
     Xi = (3.0 / 4.0) * (4.0 - params["Kprime_0"])
     Zeta = (3.0 / 8.0) * (
@@ -45,27 +45,46 @@ def bulk_modulus_fourth(volume, params):
 
 
 def volume_fourth_order(pressure, params):
+    """
+    Volume according to the fourth-order
+    Birch-Murnaghan equation of state.
+
+    :param pressure: Pressure in the same units that are supplied for the reference bulk
+    modulus (params['K_0'])
+    :type pressure: float
+    :param params: parameter dictionary
+    :type params: dictionary
+    :return: V/V_0
+    :rtype: float
+    """
 
     def delta_pressure(x):
-        return birch_murnaghan_fourth(params["V_0"] / x, params) - pressure
+        return pressure_birch_murnaghan_fourth(params["V_0"] / x, params) - pressure
 
     try:
         sol = bracket(delta_pressure, params["V_0"], 1.0e-2 * params["V_0"])
-    except:
+    except ValueError:
         raise ValueError(
             "Cannot find a volume, perhaps you are outside of the range of validity for the equation of state?"
         )
     return opt.brentq(delta_pressure, sol[0], sol[1])
 
 
-def birch_murnaghan_fourth(x, params):
+def pressure_birch_murnaghan_fourth(invVrel, params):
     """
-    equation for the fourth order birch-murnaghan equation of state, returns
-    pressure in the same units that are supplied for the reference bulk
+    Pressure according to the fourth-order
+    Birch-Murnaghan equation of state.
+
+    :param invVrel: V/V_0
+    :type invVrel: float or numpy array
+    :param params: parameter dictionary
+    :type params: dictionary
+    :return: Pressure in the same units that are supplied for the reference bulk
     modulus (params['K_0'])
+    :rtype: float or numpy array
     """
 
-    f = 0.5 * (pow(x, 2.0 / 3.0) - 1.0)
+    f = 0.5 * (pow(invVrel, 2.0 / 3.0) - 1.0)
     Xi = (3.0 / 4.0) * (4.0 - params["Kprime_0"])
     Zeta = (3.0 / 8.0) * (
         (params["K_0"] * params["Kprime_prime_0"])
@@ -96,7 +115,7 @@ def volume(self, pressure, temperature, params):
         return volume_fourth_order(pressure, params)
 
     def pressure(self, temperature, volume, params):
-        return birch_murnaghan_fourth(params["V_0"] / volume, params)
+        return pressure_birch_murnaghan_fourth(params["V_0"] / volume, params)
 
     def isothermal_bulk_modulus_reuss(self, pressure, temperature, volume, params):
         """
diff --git a/burnman/eos/modified_tait.py b/burnman/eos/modified_tait.py
index f59d7399..f2bc5e2a 100644
--- a/burnman/eos/modified_tait.py
+++ b/burnman/eos/modified_tait.py
@@ -30,15 +30,21 @@ def tait_constants(params):
     return a, b, c
 
 
-def modified_tait(x, params):
+def pressure_modified_tait(Vrel, params):
     """
-    equation for the modified Tait equation of state, returns
-    pressure in the same units that are supplied for the reference bulk
-    modulus (params['K_0'])
+    Pressure according to the modified Tait equation of state.
     EQ 2 from Holland and Powell, 2011
+
+    :param Vrel: V/V_0
+    :type Vrel: float or numpy array
+    :param params: Parameter dictionary
+    :type params: dictionary
+    :return: pressure in the same units that are supplied for the reference bulk
+    modulus (params['K_0'])
+    :rtype: float or numpy array
     """
     a, b, c = tait_constants(params)
-    return (np.power((x + a - 1.0) / a, -1.0 / c) - 1.0) / b + params["P_0"]
+    return (np.power((Vrel + a - 1.0) / a, -1.0 / c) - 1.0) / b + params["P_0"]
 
 
 def volume(pressure, params):
@@ -47,8 +53,8 @@ def volume(pressure, params):
     EQ 12
     """
     a, b, c = tait_constants(params)
-    x = 1 - a * (1.0 - np.power((1.0 + b * (pressure - params["P_0"])), -1.0 * c))
-    return x * params["V_0"]
+    Vrel = 1.0 - a * (1.0 - np.power((1.0 + b * (pressure - params["P_0"])), -1.0 * c))
+    return Vrel * params["V_0"]
 
 
 def bulk_modulus(pressure, params):
@@ -113,7 +119,7 @@ def pressure(self, temperature, volume, params):
         """
         Returns pressure [Pa] as a function of temperature [K] and volume[m^3]
         """
-        return modified_tait(volume / params["V_0"], params)
+        return pressure_modified_tait(volume / params["V_0"], params)
 
     def isothermal_bulk_modulus_reuss(self, pressure, temperature, volume, params):
         """