rock-physics-open 0.3.2__py3-none-any.whl

rock_physics_open/equinor_utilities/snapshot_test_utilities/snapshots.py

@@ -0,0 +1,97 @@
+import inspect
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+INITIATE = False
+
+SYSTEM_AND_DEBUG_FCN = [
+    "pydev",
+    "ipython-input",
+    "interactiveshell",
+    "async_helpers",
+    "handle_snapshots",
+    "run_code",
+    "run_ast_nodes",
+    "run_cell_async",
+    "_pseudo_sync_runner",
+    "_run_cell",
+    "run_cell",
+    "add_exec",
+    "do_add_exec",
+    "add_exec",
+    "ipython_exec_code",
+    "console_exec",
+    "do_it",
+    "process_internal_commands",
+    "_do_wait_suspend",
+    "do_wait_suspend",
+    "compare_snapshots",
+    "handle_snapshots",
+    "wrapper",
+    "run_tests",
+    "<module>",
+]
+
+
+def get_snapshot_name(
+    step: int = 1,
+    include_filename: bool = True,
+    include_function_name: bool = True,
+    include_extension: bool = True,
+    include_snapshot_dir: bool = True,
+) -> str:
+    """
+    Parameters
+    ----------
+    step: number of steps in the trace to collect information from
+    include_snapshot_dir: absolute directory name included in snapshot name
+    include_filename: whether to include filename in snapshot name
+    include_function_name: whether to include function name in snapshot name
+    include_extension: whether to include extension in snapshot name
+
+    Returns
+    -------
+    name of snapshot file
+    """
+    trace = inspect.stack()
+    for frame in trace[step:]:
+        if not any(keyword in frame.function for keyword in SYSTEM_AND_DEBUG_FCN):
+            break
+    else:
+        frame = trace[step]
+
+    dir_name = Path(frame.filename).parents[1] / "data" / "snapshots"
+    file_name = Path(frame.filename).stem if include_filename else ""
+    function_name = frame.function if include_function_name else ""
+    extension = ".npz" if include_extension else ""
+    parts = [part for part in [file_name, function_name] if part]
+    base_name = "_".join(parts) + extension
+    return str(dir_name / base_name) if include_snapshot_dir else base_name
+
+
+def store_snapshot(snapshot_name: str, *args: np.ndarray) -> bool:
+    """
+    Examples
+    --------
+    In case there are multiple arrays to store:
+    store_snapshot(snapshot_name='snap_to_store.npz', *args)
+
+    Important: If there is only one array to store:
+    store_snapshot(snapshot_name='snap_to_store.npz', args)
+    """
+    try:
+        np.savez(snapshot_name, *args)
+    except IOError as e:
+        raise IOError(f"Could not store snapshot {snapshot_name}: {e}")
+    return True
+
+
+def read_snapshot(snapshot_name: str) -> tuple[npt.NDArray[Any], ...]:
+    try:
+        with np.load(snapshot_name) as stored_npz:
+            return tuple(stored_npz[arr_name] for arr_name in stored_npz.files)
+    except IOError as e:
+        raise ValueError(f"unable to load snapshot {snapshot_name}: {e}")

rock_physics_open/equinor_utilities/std_functions/__init__.py

@@ -0,0 +1,43 @@
+from .backus_ave import backus_average
+from .dvorkin_nur import dvorkin_contact_cement
+from .gassmann import gassmann, gassmann2, gassmann_dry
+from .hashin_shtrikman import (
+    hashin_shtrikman,
+    hashin_shtrikman_average,
+    hashin_shtrikman_walpole,
+    multi_hashin_shtrikman,
+)
+from .hertz_mindlin import hertz_mindlin
+from .moduli_velocity import moduli, velocity
+from .reflection_eq import aki_richards, smith_gidlow
+from .rho import rho_b, rho_m
+from .voigt_reuss_hill import multi_voigt_reuss_hill, reuss, voigt, voigt_reuss_hill
+from .walton import walton_smooth
+from .wood_brie import brie, multi_wood, wood
+
+__all__ = [
+    "backus_average",
+    "dvorkin_contact_cement",
+    "gassmann",
+    "gassmann2",
+    "gassmann_dry",
+    "hashin_shtrikman",
+    "hashin_shtrikman_average",
+    "hashin_shtrikman_walpole",
+    "multi_hashin_shtrikman",
+    "hertz_mindlin",
+    "moduli",
+    "velocity",
+    "aki_richards",
+    "smith_gidlow",
+    "rho_b",
+    "rho_m",
+    "multi_voigt_reuss_hill",
+    "reuss",
+    "voigt",
+    "voigt_reuss_hill",
+    "walton_smooth",
+    "brie",
+    "multi_wood",
+    "wood",
+]

rock_physics_open/equinor_utilities/std_functions/backus_ave.py

@@ -0,0 +1,68 @@
+import numpy as np
+import numpy.typing as npt
+
+
+def backus_average(
+    vp1: npt.NDArray[np.float64],
+    vs1: npt.NDArray[np.float64],
+    rho1: npt.NDArray[np.float64],
+    vp2: npt.NDArray[np.float64],
+    vs2: npt.NDArray[np.float64],
+    rho2: npt.NDArray[np.float64],
+    f1: npt.NDArray[np.float64],
+) -> tuple[
+    npt.NDArray[np.float64],
+    npt.NDArray[np.float64],
+    npt.NDArray[np.float64],
+    npt.NDArray[np.float64],
+    npt.NDArray[np.float64],
+]:
+    """
+    Backus average for a combination of two phases. The individual phases are isotropic
+    but the resulting effective medium is not.
+
+    Parameters
+    ----------
+    vp1 : np.ndarray
+        Pressure wave velocity for phase 1 [m/s].
+    vs1 : np.ndarray
+        Shear wave velocity for phase 1 [m/s].
+    rho1 : np.ndarray
+        Density for phase 1 [kg/m^3].
+    vp2 : np.ndarray
+        Pressure wave velocity for phase 2 [m/s].
+    vs2 : np.ndarray
+        Shear wave velocity for phase 2 [m/s].
+    rho2 : np.ndarray
+        Density for phase 2 [kg/m^3].
+    f1 : np.ndarray
+        Fraction of phase 1.
+
+    Returns
+    -------
+    tuple
+        vpv, vsv, vph, vsh, rho : np.ndarray
+        vpv: vertical pressure velocity, vsv: vertical shear velocity, vph: horizontal pressure velocity,
+        vsh: horizontal shear velocity, rho: density.
+    """
+
+    a = (
+        4 * f1 * rho1 * vs1**2 * (1 - vs1**2 / vp1**2)
+        + 4 * (1 - f1) * rho2 * vs2**2 * (1 - (vs2 / vp2) ** 2)
+        + (f1 * (1 - 2 * (vs1 / vp1) ** 2) + (1 - f1) * (1 - 2 * (vs2 / vp2) ** 2)) ** 2
+        * (1 / (f1 / (rho1 * vp1**2) + (1 - f1) / (rho2 * vp2**2)))
+    )
+
+    c = 1 / (f1 / (rho1 * vp1**2) + (1 - f1) / (rho2 * vp2**2))
+    d = 1 / (f1 / (rho1 * vs1**2) + (1 - f1) / (rho2 * vs2**2))
+
+    m = f1 * rho1 * vs1**2 + (1 - f1) * rho2 * vs2**2
+
+    rho = f1 * rho1 + (1 - f1) * rho2
+
+    vpv = np.sqrt(c / rho)
+    vsv = np.sqrt(d / rho)
+    vph = np.sqrt(a / rho)
+    vsh = np.sqrt(m / rho)
+
+    return vpv, vsv, vph, vsh, rho

rock_physics_open/equinor_utilities/std_functions/dvorkin_nur.py

@@ -0,0 +1,77 @@
+import numpy as np
+import numpy.typing as npt
+
+
+def dvorkin_contact_cement(
+    frac_cem: npt.NDArray[np.float64],
+    por0_sst: npt.NDArray[np.float64],
+    mu0_sst: npt.NDArray[np.float64],
+    k0_sst: npt.NDArray[np.float64],
+    mu0_cem: npt.NDArray[np.float64],
+    k0_cem: npt.NDArray[np.float64],
+    vs_red: npt.NDArray[np.float64],
+    c: float,
+) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
+    """
+    Dvorkin-Nur contact cement model for estimation of elastic moduli.
+
+    Parameters
+    ----------
+    frac_cem : numpy.ndarray
+        Cement fraction of volume [ratio].
+    por0_sst : numpy.ndarray
+        Critical porosity of sand [ratio].
+    mu0_sst : numpy.ndarray
+        Mineral shear modulus of sand [Pa].
+    k0_sst : numpy.ndarray
+        Mineral bulk modulus of sand [Pa].
+    mu0_cem : numpy.ndarray
+        Mineral shear modulus of cement [Pa].
+    k0_cem : numpy.ndarray
+        Mineral bulk modulus of cement [Pa].
+    vs_red : numpy.ndarray
+        Shear modulus reduction factor [ratio].
+    c : float
+        Coordination number (grain contacts per grain) [unitless].
+
+    Returns
+    -------
+    tuple
+        k_cc, mu_cc : numpy.ndarray.
+        k_cc: bulk modulus [Pa], mu_cc: shear modulus [Pa].
+    """
+    alpha = (2 * frac_cem / (3 * (1 - por0_sst))) ** 0.5
+    poiss = (3 * k0_sst - 2 * mu0_sst) / (2 * (3 * k0_sst + mu0_sst))
+    poiss_c = (3 * k0_cem - 2 * mu0_cem) / (2 * (3 * k0_cem + mu0_cem))
+    a_an = (2 * mu0_cem / (np.pi * mu0_sst)) * (
+        (1 - poiss) * (1 - poiss_c) / (1 - 2 * poiss_c)
+    )
+    a_at = mu0_cem / (np.pi * mu0_sst)
+
+    a_t = (
+        -1e-2
+        * (2.26 * poiss**2 + 2.07 * poiss + 2.3)
+        * a_at ** (0.079 * poiss**2 + 0.1754 * poiss - 1.342)
+    )
+    b_t = (0.0573 * poiss**2 + 0.0937 * poiss + 0.202) * a_at ** (
+        0.0274 * poiss**2 + 0.0529 * poiss - 0.8765
+    )
+    c_t = (
+        1e-4
+        * (9.654 * poiss**2 + 4.945 * poiss + 3.1)
+        * a_at ** (0.01867 * poiss**2 + 0.4011 * poiss - 1.8186)
+    )
+
+    s_t = a_t * alpha**2 + b_t * alpha + c_t
+
+    c_n = 0.00024649 * a_an ** (-1.9864)
+    b_n = 0.20405 * a_an ** (-0.89008)
+    a_n = -0.024153 * a_an ** (-1.3646)
+
+    s_n = a_n * alpha**2 + b_n * alpha + c_n
+
+    m0_cem = k0_cem + 4 / 3 * mu0_cem
+    k_cc = (1 / 6) * c * (1 - por0_sst) * m0_cem * s_n
+    mu_cc = (3 / 5) * k_cc + vs_red * (3 / 20) * c * (1 - por0_sst) * mu0_cem * s_t
+
+    return k_cc, mu_cc

rock_physics_open/equinor_utilities/std_functions/gassmann.py

@@ -0,0 +1,165 @@
+import warnings
+from typing import cast
+
+import numpy as np
+import numpy.typing as npt
+
+from rock_physics_open.equinor_utilities.gen_utilities import dim_check_vector
+
+
+def gassmann(
+    k_dry: npt.NDArray[np.float64],
+    por: npt.NDArray[np.float64],
+    k_fl: npt.NDArray[np.float64],
+    k_min: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64]:
+    """
+    Fluid substitution according to the Gassmann equation.
+
+    Parameters
+    ----------
+    k_dry : np.ndarray
+        Dry rock bulk modulus [Pa].
+    por : np.ndarray
+        Porosity [fraction].
+    k_fl : np.ndarray
+        Fluid bulk modulus.
+    k_min : np.ndarray
+        Mineral bulk modulus [Pa].
+
+    Returns
+    -------
+    np.ndarray
+        k_sat: bulk modulus for saturated rock [Pa]
+    """
+    k_dry, por, k_fl, k_min = cast(
+        list[npt.NDArray[np.float64]],
+        dim_check_vector((k_dry, por, k_fl, k_min)),
+    )
+
+    idx = np.logical_or(k_dry == k_min, por == 0)
+    k_sat = np.ones(k_dry.shape) * np.nan
+    b = k_dry[~idx] / (k_min[~idx] - k_dry[~idx]) + k_fl[~idx] / (
+        (k_min[~idx] - k_fl[~idx]) * por[~idx]
+    )
+    idx1 = b < 0
+    if any(idx1):
+        b[idx1] = np.nan
+
+    k_sat[~idx] = b / (1 + b) * k_min[~idx]
+    k_sat[idx] = k_min[idx]
+
+    return k_sat
+
+
+def gassmann2(
+    k_sat_1: npt.NDArray[np.float64],
+    k_fl_1: npt.NDArray[np.float64],
+    k_fl_2: npt.NDArray[np.float64],
+    por: npt.NDArray[np.float64],
+    k_min: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64]:
+    """
+    Fluid substitution by Gassmann method with substitution of one fluid to another
+
+    Parameters
+    ----------
+    k_sat_1 : np.ndarray
+        bulk modulus for saturated rock with original fluid [Pa]
+    k_fl_1 : np.ndarray
+        bulk modulus for original fluid [Pa]
+    k_fl_2 : np.ndarray
+        bulk modulus for replaced fluid [Pa]
+    por : np.ndarray
+        porosity of rock [fraction]
+    k_min : np.ndarray
+        mineral bulk modulus of rock [Pa]
+
+    Returns
+    -------
+    np.ndarray
+        k_sat_2: bulk modulus of rock saturated with replaced fluid [Pa]
+    """
+    k_sat_1, k_fl_1, k_fl_2, por, k_min = cast(
+        list[npt.NDArray[np.float64]],
+        dim_check_vector((k_sat_1, k_fl_1, k_fl_2, por, k_min)),
+    )
+
+    idx = np.any(
+        np.array([k_sat_1 == k_min, por == 0, k_fl_1 == k_min, k_fl_2 == k_min]), axis=0
+    )
+
+    k_sat_2 = np.ones(k_sat_1.shape) * np.nan
+
+    b = (
+        k_fl_2[~idx] / (por[~idx] * (k_min[~idx] - k_fl_2[~idx]))
+        - k_fl_1[~idx] / (por[~idx] * (k_min[~idx] - k_fl_1[~idx]))
+        + k_sat_1[~idx] / (k_min[~idx] - k_sat_1[~idx])
+    )
+
+    idx1 = b < 0
+    if any(idx1):
+        warn_str = (
+            "{0:d} unstable solution(s) to Gassmann equation, changed to NaN".format(
+                np.sum(idx1)
+            )
+        )
+        warnings.warn(warn_str, UserWarning)
+        b[idx1] = np.nan
+
+    k_sat_2[~idx] = b / (1 + b) * k_min[~idx]
+    k_sat_2[idx] = k_sat_1[idx]
+
+    return k_sat_2
+
+
+def gassmann_dry(
+    k_sat: npt.NDArray[np.float64],
+    por: npt.NDArray[np.float64],
+    k_fl: npt.NDArray[np.float64],
+    k_min: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64]:
+    """
+    Dry rock properties of saturated rock by Gassmann equation
+
+    Parameters
+    ----------
+    k_sat : np.ndarray
+        saturated rock bulk modulus [Pa]
+    por : np.ndarray
+        porosity of rock [fraction]
+    k_fl : np.ndarray
+        bulk modulus of fluid [Pa]
+    k_min : np.ndarray
+        bulk modulus of mineral [Pa]
+
+    Returns
+    -------
+    np.ndarray
+        k_dry: dry rock bulk modulus [Pa]
+    """
+    k_sat, por, k_fl, k_min = cast(
+        list[npt.NDArray[np.float64]],
+        dim_check_vector((k_sat, por, k_fl, k_min)),
+    )
+
+    idx = np.any(np.array([k_sat == k_min, por == 0, k_fl == k_min]), axis=0)
+    k_dry = np.ones(k_sat.shape)
+    b = k_sat[~idx] / (k_min[~idx] - k_sat[~idx]) - k_fl[~idx] / (
+        (k_min[~idx] - k_fl[~idx]) * por[~idx]
+    )
+
+    idx1 = b < 0
+    if any(idx1):
+        warn_str = (
+            "{0:d} unstable solution(s) to Gassmann equation, changed to NaN".format(
+                np.sum(idx1)
+            )
+        )
+        warnings.warn(warn_str, UserWarning)
+        b[idx1] = np.nan
+
+    k_dry[~idx] = b / (1 + b) * k_min[~idx]
+    k_dry[idx] = k_min[idx]
+
+    return k_dry

rock_physics_open/equinor_utilities/std_functions/hashin_shtrikman.py

@@ -0,0 +1,224 @@
+from typing import Literal, cast
+
+import numpy as np
+import numpy.typing as npt
+
+from rock_physics_open.equinor_utilities.gen_utilities import dim_check_vector
+
+
+def hashin_shtrikman(
+    k1: npt.NDArray[np.float64],
+    mu1: npt.NDArray[np.float64],
+    k2: npt.NDArray[np.float64],
+    mu2: npt.NDArray[np.float64],
+    f: npt.NDArray[np.float64],
+) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
+    """
+    Hashin-Sktrikman upper or lower according to ordering of phases.
+
+    Parameters
+    ----------
+    k1 : np.ndarray
+        Bulk modulus of phase 1 [Pa].
+    mu1 : np.ndarray
+        Shear modulus of phase 1 [Pa].
+    k2 : np.ndarray
+        Bulk modulus of phase 2 [Pa].
+    mu2 : np.ndarray
+        Shear modulus of phase 2 [Pa].
+    f : np.ndarray
+        Fraction of phase 1 [fraction].
+
+    Returns
+    -------
+    tuple
+        k, mu : np.ndarray.
+        k: effective bulk modulus [Pa], mu: effective shear modulus [Pa].
+    """
+    k = k1 + (1 - f) * (k2 - k1) / (1 + (k2 - k1) * f * (k1 + 4 / 3 * mu1) ** -1)
+    mu = mu1 + (1 - f) * (mu2 - mu1) / (
+        1 + 2 * (mu2 - mu1) * f * (k1 + 2 * mu1) / (5 * mu1 * (k1 + 4 / 3 * mu1))
+    )
+
+    return k, mu
+
+
+def hashin_shtrikman_average(
+    k1: npt.NDArray[np.float64],
+    mu1: npt.NDArray[np.float64],
+    k2: npt.NDArray[np.float64],
+    mu2: npt.NDArray[np.float64],
+    f: npt.NDArray[np.float64],
+) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
+    """
+    Average of Hashin-Shtrikman upper and lower bound.
+
+    Parameters
+    ----------
+    k1 : np.ndarray
+        Bulk modulus of phase 1 [Pa].
+    mu1 : np.ndarray
+        Shear modulus of phase 1 [Pa].
+    k2 : np.ndarray
+        Bulk modulus of phase 2 [Pa].
+    mu2 : np.ndarray
+        Shear modulus of phase 2 [Pa].
+    f : np.ndarray
+        Fraction of phase 1 [fraction].
+
+    Returns
+    -------
+    tuple
+        k_av, mu_av : np.ndarray.
+        k_av: effective bulk modulus [Pa], mu_av: effective shear modulus [Pa]
+    """
+    k_hs1, mu_hs1 = hashin_shtrikman(k1, mu1, k2, mu2, f)
+    k_hs2, mu_hs2 = hashin_shtrikman(k2, mu2, k1, mu1, 1 - f)
+
+    k_av = (k_hs1 + k_hs2) / 2
+    mu_av = (mu_hs1 + mu_hs2) / 2
+
+    return k_av, mu_av
+
+
+def hashin_shtrikman_walpole(
+    k1: npt.NDArray[np.float64],
+    mu1: npt.NDArray[np.float64],
+    k2: npt.NDArray[np.float64],
+    mu2: npt.NDArray[np.float64],
+    f1: npt.NDArray[np.float64],
+    bound: Literal["upper", "lower"] = "lower",
+) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
+    """
+    Hashin-Shtrikman upper bound is obtained when the stiffest material is
+    termed 1 and vice versa for lower bound. Tricky in cases like Quartz -
+    Calcite where the K and Mu have opposed values. HS - Walpole is
+    generalised to regard highest and lowest values in each case. The default
+    is to generate lower bound.
+
+    Parameters
+    ----------
+    k1 : np.ndarray
+        Bulk modulus of phase 1 [Pa].
+    mu1 : np.ndarray
+        Shear modulus of phase 1 [Pa].
+    k2 : np.ndarray
+        Bulk modulus of phase 2 [Pa].
+    mu2 : np.ndarray
+        Shear modulus of phase 2 [Pa].
+    f1 : np.ndarray or float
+        Fraction of phase 1 [fraction].
+    bound: str
+        'upper' or 'lower' selection of upper of lower bound of effective medium.
+    Returns
+    -------
+    tuple
+        k, mu : np.ndarray.
+        k: effective bulk modulus [Pa], mu: effective shear modulus [Pa].
+    """
+    k1, mu1, k2, mu2, f1 = cast(
+        list[npt.NDArray[np.float64]],
+        dim_check_vector((k1, mu1, k2, mu2, f1)),
+    )
+    if bound.lower() not in ["lower", "upper"]:
+        raise ValueError(f'{__file__}: bound must be one of "lower" or "upper"')
+
+    idx_k = k1 == k2
+    idx_mu = mu1 == mu2
+    f2 = 1 - f1
+
+    if bound.lower() == "lower":
+        k_m = np.minimum(k1, k2)
+        mu_m = np.minimum(mu1, mu2)
+    else:
+        k_m = np.maximum(k1, k2)
+        mu_m = np.maximum(mu1, mu2)
+
+    k = np.zeros(k1.shape)
+    mu = np.zeros(k1.shape)
+
+    if np.any(idx_k):
+        k[idx_k] = k1[idx_k]
+    if np.any(~idx_k):
+        k[~idx_k] = k1[~idx_k] + f2[~idx_k] / (
+            (k2[~idx_k] - k1[~idx_k]) ** -1
+            + f1[~idx_k] * (k1[~idx_k] + 4 / 3 * mu_m[~idx_k]) ** -1
+        )
+    if np.any(idx_mu):
+        mu[idx_mu] = mu1[idx_mu]
+    if np.any(~idx_mu):
+        mu[~idx_mu] = mu1[~idx_mu] + f2[~idx_mu] / (
+            (mu2[~idx_mu] - mu1[~idx_mu]) ** -1
+            + f1[~idx_mu]
+            * (
+                mu1[~idx_mu]
+                + mu_m[~idx_mu]
+                / 6
+                * (9 * k_m[~idx_mu] + 8 * mu_m[~idx_mu])
+                / (k_m[~idx_mu] + 2 * mu_m[~idx_mu])
+            )
+            ** -1
+        )
+
+    return k, mu
+
+
+def multi_hashin_shtrikman(
+    *coeffs: npt.NDArray[np.float64],
+    mode: Literal["average", "upper", "lower"] = "average",
+) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
+    """
+    Hashin-Shtrikman effective medium calculation for multi-mineral case.
+
+    Parameters
+    ----------
+    coeffs : np.ndarray
+        Triplets of vectors with k (bulk modulus [Pa]), mu (shear modulus [Pa]) and fraction for each mineral.
+    mode : str
+        'average', 'upper' or 'lower'.
+
+    Returns
+    -------
+    tuple
+        k_hs, mu_hs : np.ndarray.
+        k_hs, mu_hs - bulk modulus and shear modulus for effective medium [Pa].
+    """
+    if not len(coeffs) % 3 == 0:
+        raise ValueError(
+            "multi_hashin_shtrikman: inputs not vectors of k, mu and fraction for each mineral"
+        )
+
+    k_arr = np.array(coeffs[::3])
+    mu_arr = np.array(coeffs[1::3])
+    f = np.array(coeffs[2::3])
+    if not np.all(
+        cast(npt.NDArray[np.float64], np.around(np.sum(f, axis=0), decimals=6)) == 1.0
+    ):
+        raise ValueError("multi_hashin_shtrikman: all fractions do not add up to 1.0")
+
+    if mode.lower() not in ["average", "upper", "lower"]:
+        raise ValueError(
+            'multi_hashin_shtrikman: mode is not one of "average", "upper" or "lower"'
+        )
+
+    k_min = np.min(k_arr, axis=0)
+    k_max = np.max(k_arr, axis=0)
+    mu_min = np.min(mu_arr, axis=0)
+    mu_max = np.max(mu_arr, axis=0)
+
+    k_hs_upper = np.sum(f / (k_arr + 4 / 3 * mu_max), axis=0) ** -1 - 4 / 3 * mu_max
+    k_hs_lower = np.sum(f / (k_arr + 4 / 3 * mu_min), axis=0) ** -1 - 4 / 3 * mu_min
+
+    zeta_max = mu_max / 6 * (9 * k_max + 8 * mu_max) / (k_max + 2 * mu_max)
+    zeta_min = mu_min / 6 * (9 * k_min + 8 * mu_min) / (k_min + 2 * mu_min)
+
+    mu_hs_upper = np.sum(f / (mu_arr + zeta_max), axis=0) ** -1 - zeta_max
+    mu_hs_lower = np.sum(f / (mu_arr + zeta_min), axis=0) ** -1 - zeta_min
+
+    if mode == "lower":
+        return k_hs_lower, mu_hs_lower
+    if mode == "upper":
+        return k_hs_upper, mu_hs_upper
+    k_hs = 0.5 * (k_hs_upper + k_hs_lower)
+    mu_hs = 0.5 * (mu_hs_upper + mu_hs_lower)
+    return k_hs, mu_hs