Refactor: Eyring reverberation time calculation

pyrato/parametric.py

@@ -214,46 +214,73 @@ def mean_free_path(
     return 4 * volume / surface_area
 
 
-def reverberation_time_eyring(volume,surface,mean_alpha):
+def reverberation_time_eyring(
+        volume: float,
+        surface_area: float,
+        mean_absorption: np.typing.NDArray[float],
+        speed_of_sound: float = 343.4,
+    ):
     r"""
-    function which calculates reverberation time in rooms as
-    defined by Carl F. Eyring.
+    Calculate the reverberation time in rooms as defined by Carl Eyring.
+
+    The reverberation time is calculated according to Ref. [#]_ as
 
     .. math::
-        T_{60} = -0.161 \frac{\text{volume}}{\text{surface} \cdot
-            \ln(1 - \text{mean\_alpha})}
+        T_{60} = \frac{24 \cdot \ln(10)}{c}
+        \cdot \frac{V}{S \ln(1 - \tilde{\alpha})}
+
+    where :math:`V` is the room volume, :math:`S` is the total surface area
+    of the room, :math:`\tilde{\alpha}` is the average absorption coefficient
+    of the room surfaces, and :math:`c` is the speed of sound.
 
     Parameters
     ----------
-    volume : float, np.ndarray
-        Room volume in m3
-    surface : float, np.ndarray
-        Surface areas of all surfaces in the room in m2
-    mean_alpha : float, np.ndarray
-        Average absorption coefficient of room surfaces
+    volume : float
+        Room volume in :math:`\mathrm{m}^3`
+    surface_area : float
+        Total surface area of the room in :math:`\mathrm{m}^2`
+    mean_absorption : float, numpy.ndarray
+        Average absorption coefficient of room surfaces between 0 and 1. If
+        an array is passed, the reverberation time is calculated for each value
+        in the array.
+    speed_of_sound : float
+        Speed of sound in m/s. Default is 343.4 m/s, which corresponds to the
+        speed of sound in air at 20 °C.
 
     Returns
     -------
-    reverberation_time_eyring: double
-         Eyring reverberation time in s
+    float, numpy.ndarray
+        Reverberation time in seconds. The shape matches the shape of the input
+        variable `mean_absorption`.
+
+    Examples
+    --------
+    >>> from pyrato.parametric import reverberation_time_eyring
+    >>> import numpy as np
+    >>> volume = 64
+    >>> surface_area = 96
+    >>> mean_absorption = [0.1, 0.3, 0.4]
+    >>> reverb_time = reverberation_time_eyring(
+    >>>     volume, surface_area, mean_absorption)
+    >>> np.round(reverb_time, 2)
 
     References
     ----------
-    .. [#] Eyring, C.F., 1930. Reverberation time in “dead” rooms. The Journal
-    of the Acoustical Society of America, 1(2A_Supplement), pp.168-168.
+    .. [#] Eyring, C.F., 1930. Reverberation time in "dead" rooms. The Journal
+           of the Acoustical Society of America, 1(2A_Supplement), pp.168-168.
 
     """
-
-    if volume <= 0:
+    if np.any(volume) <= 0:
         raise ValueError("Volume should be larger than 0")
-    if surface <= 0:
-        raise ValueError("Surface should be larger than 0")
-    if mean_alpha <0 or mean_alpha >1:
-        raise ValueError("mean_alpha should be between 0 and 1")
+    if np.any(surface_area) <= 0:
+        raise ValueError("Surface area should be larger than 0")
 
-    T60 = -0.161 * (volume / (surface * np.log(1 - mean_alpha)))
+    mean_absorption = np.asarray(mean_absorption)
+    if np.any(mean_absorption < 0) or np.any(mean_absorption > 1):
+        raise ValueError("mean_absorption should be between 0 and 1")
 
-    return T60
+    factor = 24 * np.log(10) / speed_of_sound
+    return -factor * (volume / (surface_area * np.log(1 - mean_absorption)))
 
 
 def calculate_sabine_reverberation_time(surfaces, alphas, volume):

tests/test_parametric_eyring.py

@@ -1,4 +1,4 @@
-"""Tests for Eyring's equation"""
+"""Tests for Eyring's equation."""
 import numpy.testing as npt
 import pytest
 from pyrato.parametric import reverberation_time_eyring
@@ -7,20 +7,18 @@ def test_analytic_Eyring():
     volume = 64
     surface = 96
     mean_alpha = 0.2
-    reverb_test = reverberation_time_eyring(volume,surface,mean_alpha)
+    reverb_test = reverberation_time_eyring(volume, surface, mean_alpha)
     npt.assert_allclose(reverb_test, 0.481, rtol=1e-3)
 
-@pytest.mark.parametrize("volume, surface", [(0, -2), (-1, 0)])
+@pytest.mark.parametrize(("volume", "surface"), [(0, -2), (-1, 0)])
 def test_input_geometry_Eyring(volume, surface):
     mean_alpha = 0.2
     with pytest.raises(ValueError, match="should be larger than 0"):
-        reverberation_time_eyring(volume,surface,mean_alpha)
+        reverberation_time_eyring(volume, surface, mean_alpha)
 
 @pytest.mark.parametrize("mean_alpha", [-1, 2])
 def test_input_alpha_Eyring(mean_alpha):
     volume = 64
     surface = 96
-    with pytest.raises(
-        ValueError, match="mean_alpha should be between 0 and 1"
-    ):
-        reverberation_time_eyring(volume,surface,mean_alpha)
+    with pytest.raises(ValueError, match="should be between 0 and 1"):
+        reverberation_time_eyring(volume, surface, mean_alpha)