fmu-pem 0.0.1__py3-none-any.whl

fmu/pem/pem_functions/fluid_properties.py

@@ -0,0 +1,281 @@
+# pylint: disable=missing-module-docstring
+import warnings
+from typing import Tuple, Union
+
+import numpy as np
+from rock_physics_open import fluid_models as flag
+from rock_physics_open import span_wagner
+from rock_physics_open.equinor_utilities.std_functions import brie, multi_wood
+
+from fmu.pem import INTERNAL_EQUINOR
+
+if INTERNAL_EQUINOR:
+    from rock_physics_open.fluid_models import saturations_below_bubble_point
+
+from rock_physics_open.fluid_models.oil_model.oil_bubble_point import bp_standing
+
+from fmu.pem.pem_utilities import (
+    EffectiveFluidProperties,
+    Fluids,
+    SimRstProperties,
+    filter_and_one_dim,
+    reverse_filter_and_restore,
+    to_masked_array,
+)
+from fmu.pem.pem_utilities.enum_defs import CO2Models, FluidMixModel
+
+
+def effective_fluid_properties(
+    props: list[SimRstProperties] | SimRstProperties,
+    fluid_params: Fluids,
+) -> list[EffectiveFluidProperties]:
+    """effective_fluid_properties
+    Calculate effective fluid properties (bulk modulus, density) from a fluid mix.
+
+    6/1-25: Now also incorporating fluid properties in the case where the formation
+    pressure is below the oil bubble point.
+
+    Parameters
+    ----------
+    props : Union
+        list of dicts or a single dict with saturation, GOR and pressure per
+        time step
+    fluid_params : Fluids class
+        parameter set containing fluid parameters for FLAG models
+
+    Returns
+    -------
+    list
+        fluid properties (bulk modulus and density) per time step
+    """
+    props = _verify_inputs(props)
+    prop_list = []
+    for prop in props:
+        # Initial check of saturation for gas and brine and calculation of oil
+        # saturation
+        sat_wat, sat_gas, sat_oil = _saturation_check(prop.swat, prop.sgas)
+
+        gor = prop.rs
+
+        fluid_keys = ("vp", "density", "bulk_modulus")
+
+        # Convert pressure from bar to Pa
+        pres = 1.0e5 * prop.pressure
+        mix_model = fluid_params.mix_method
+        brie_exp = fluid_params.brie_exponent
+
+        # Salinity and temperature are either taken as constants from config file or
+        # from eclipse simulator model
+        if fluid_params.salinity_from_sim:
+            # Convert from ppk to ppm
+            salinity = 1000.0 * prop.salt
+        else:
+            salinity = to_masked_array(fluid_params.brine.salinity, sat_wat)
+        # Temperature will normally be set as a constant. It can come from eclipse in
+        # the case a compositional fluid model is run.
+        if fluid_params.temperature_from_sim:
+            temp = prop.temp
+        else:
+            temp = to_masked_array(fluid_params.temperature, sat_wat)
+
+        # Gas gravity has to be expanded to a masked array if it comes as a float
+        if isinstance(fluid_params.gas.gas_gravity, float):
+            gas_gravity = to_masked_array(fluid_params.gas.gas_gravity, sat_wat)
+        else:
+            gas_gravity = fluid_params.gas.gas_gravity
+
+        if hasattr(prop, "rv"):
+            (
+                mask,
+                sat_wat,
+                sat_gas,
+                sat_oil,
+                gor,
+                pres,
+                rv,
+                salinity,
+                temp,
+                gas_gravity,
+            ) = filter_and_one_dim(
+                sat_wat,
+                sat_gas,
+                sat_oil,
+                gor,
+                pres,
+                prop.rv,
+                salinity,
+                temp,
+                gas_gravity,
+            )
+        else:
+            (
+                mask,
+                sat_wat,
+                sat_gas,
+                sat_oil,
+                gor,
+                pres,
+                salinity,
+                temp,
+            ) = filter_and_one_dim(sat_wat, sat_gas, sat_oil, gor, pres, salinity, temp)
+            rv = None
+
+        # Brine
+        brine_par = fluid_params.brine
+        p_na = np.array(brine_par.perc_na)
+        p_ca = np.array(brine_par.perc_ca)
+        p_k = np.array(brine_par.perc_k)
+        brine_props = flag.brine_properties(
+            temp, pres, salinity, p_nacl=p_na, p_cacl=p_ca, p_kcl=p_k
+        )
+        brine = dict(zip(fluid_keys, brine_props))
+
+        # Oil
+        oil_par = fluid_params.oil
+        oil_gr = oil_par.gas_gravity * np.ones_like(sat_wat)
+        oil_density = oil_par.reference_density * np.ones_like(sat_wat)
+
+        # If we are below bubble point, gas will come out of solution, and this has
+        # to be taken into account
+        try:
+            idx_below_bubble_point = pres <= bp_standing(oil_density, gor, oil_gr, temp)
+            if np.any(~idx_below_bubble_point):
+                warnings.warn(
+                    f"Detected pressure below bubble point for oil in "
+                    f"{np.sum(~idx_below_bubble_point)} cells"
+                )
+        except NotImplementedError:
+            # If the function is not available, a case above bubble point is assumed
+            warnings.warn(
+                "Function for bubble point not implemented. Conditions above "
+                "bubble point is assumed."
+            )
+            idx_below_bubble_point = np.zeros_like(sat_wat)
+        try:
+            if np.any(idx_below_bubble_point):
+                sat_gas, sat_oil, gor, gas_gravity = saturations_below_bubble_point(
+                    gas_saturation_init=sat_gas,
+                    oil_saturation_init=sat_oil,
+                    brine_saturation_init=sat_wat,
+                    gor_init=gor,
+                    oil_gas_gravity=oil_gr,
+                    free_gas_gravity=gas_gravity,
+                    oil_density=oil_density,
+                    z_factor=fluid_params.gas_z_factor,
+                    pres_depl=pres,
+                    temp_res=temp,
+                )
+        except (ModuleNotFoundError, NotImplementedError):
+            warnings.warn(
+                "Function to calculate effective fluid properties below "
+                "bubble point is not implemented. Estimates of fluid "
+                "properties may be uncertain."
+            )
+
+        oil_props = flag.oil_properties(
+            temperature=temp,
+            pressure=pres,
+            gas_gravity=oil_gr,
+            rho0=oil_density,
+            gas_oil_ratio=gor,
+        )
+        oil = dict(zip(fluid_keys, oil_props))
+
+        # Gas, condensate or CO2 - select case based on CO2 flag or presence of RV
+        # property in the Eclipse restart file
+
+        if fluid_params.gas_saturation_is_co2:
+            if fluid_params.co2_model == CO2Models.FLAG and INTERNAL_EQUINOR:
+                gas_props = flag.co2_properties(temp=temp, pres=pres)
+            else:
+                gas_props = span_wagner.co2_properties(temp=temp, pres=pres)
+        else:
+            gas_par = fluid_params.gas
+            gas_gr = gas_gravity
+            gas_model = gas_par.model
+            gas_props = flag.gas_properties(temp, pres, gas_gr, model=gas_model)[0:3]
+        # The RV parameter is used to calculate condensate properties, but the inverse
+        # property (GOR) which is used as an input to the FLAG module, is Inf if RV is
+        # 0.0. An RV of 0.0 means that the gas is dry, which is already calculated
+        # NB: condensate properties calculation requires proprietary model
+        if fluid_params.calculate_condensate and (rv is not None) and INTERNAL_EQUINOR:
+            cond_par = fluid_params.condensate
+            idx_rv_zero = np.isclose(rv, 0.0, atol=1e-10)
+            if np.any(~idx_rv_zero) and INTERNAL_EQUINOR:
+                cond_gor = 1.0 / rv[~idx_rv_zero]
+                cond_gr = cond_par.gas_gravity * np.ones_like(cond_gor)
+                cond_density = cond_par.reference_density * np.ones_like(cond_gor)
+                cond_props = flag.condensate_properties(
+                    temperature=temp[~idx_rv_zero],
+                    pressure=pres[~idx_rv_zero],
+                    rho0=cond_density,
+                    gas_oil_ratio=cond_gor,
+                    gas_gravity=cond_gr,
+                )
+                for i in range(len(gas_props)):
+                    gas_props[i][~idx_rv_zero] = cond_props[i]
+
+        gas = dict(zip(fluid_keys, gas_props))
+
+        if mix_model == FluidMixModel.WOOD:
+            mixed_fluid_bulk_modulus = multi_wood(
+                [sat_wat, sat_gas, sat_oil],
+                [brine["bulk_modulus"], gas["bulk_modulus"], oil["bulk_modulus"]],
+            )
+        else:
+            mixed_fluid_bulk_modulus = brie(
+                sat_gas,
+                gas["bulk_modulus"],
+                sat_wat,
+                brine["bulk_modulus"],
+                sat_oil,
+                oil["bulk_modulus"],
+                brie_exp,
+            )
+        mixed_fluid_density = (
+            sat_wat * brine["density"]
+            + sat_gas * gas["density"]
+            + sat_oil * oil["density"]
+        )
+        mixed_fluid_density, mixed_fluid_bulk_modulus = reverse_filter_and_restore(
+            mask, mixed_fluid_density, mixed_fluid_bulk_modulus
+        )
+        fluid_props = EffectiveFluidProperties(
+            dens=mixed_fluid_density,
+            bulk_modulus=mixed_fluid_bulk_modulus,
+        )
+        prop_list.append(fluid_props)
+    return prop_list
+
+
+def _saturation_check(
+    s_water: np.ma.MaskedArray, s_gas: np.ma.MaskedArray
+) -> Tuple[np.ma.MaskedArray, ...]:
+    s_water = np.ma.MaskedArray(np.ma.clip(s_water, 0.0, 1.0))
+    s_gas = np.ma.MaskedArray(np.ma.clip(s_gas, 0.0, 1.0))
+    max_water_gas_factor = np.ma.max(s_water + s_gas)
+    if max_water_gas_factor > 1.0:
+        s_water /= max_water_gas_factor
+        s_gas /= max_water_gas_factor
+    s_oil = 1.0 - s_water - s_gas
+    return s_water, s_gas, s_oil  # type: ignore
+
+
+def _verify_inputs(inp_props):
+    if isinstance(inp_props, list):
+        if not all(isinstance(prop, SimRstProperties) for prop in inp_props):
+            raise ValueError(
+                f"{__file__}: input to effective fluid properties should be list of "
+                f"SimRstProperties or a single SimRstProperties instance, "
+                f"is {[type(prop) for prop in inp_props]}"
+            )
+        return inp_props
+    if isinstance(inp_props, dict):
+        return [
+            inp_props,
+        ]
+    # "else ..."
+    raise ValueError(
+        f"{__file__}: input to effective fluid properties should be list of "
+        f"SimRstProperties or a single SimRstProperties instance, is {type(inp_props)}"
+    )

fmu/pem/pem_functions/mineral_properties.py

@@ -0,0 +1,230 @@
+"""
+Effective mineral properties are calculated from the individual mineral properties of
+the volume fractions. In the case that only a single net-to-gross fraction is
+available, this is transformed to shale and sand fractions. A net-to-gross fraction
+can also be estimated from porosity property.
+
+If the ntg_calculation_flag is set in the PEM configuration parameter file, this will
+override settings for volume fractions. In that case net-to-gross fraction is either
+read from file, or calculated from porosity.
+"""
+
+from pathlib import Path
+from typing import List, Tuple, Union
+from warnings import warn
+
+import numpy as np
+from rock_physics_open.equinor_utilities.std_functions import (
+    multi_hashin_shtrikman,
+    multi_voigt_reuss_hill,
+)
+
+from fmu.pem.pem_utilities import (
+    MatrixProperties,
+    PemConfig,
+    SimInitProperties,
+    filter_and_one_dim,
+    get_shale_fraction,
+    import_fractions,
+    ntg_to_shale_fraction,
+    read_ntg_grid,
+    reverse_filter_and_restore,
+    to_masked_array,
+)
+from fmu.pem.pem_utilities.enum_defs import MineralMixModel, VolumeFractions
+from fmu.pem.pem_utilities.pem_config_validation import (
+    MineralProperties,
+)
+
+
+def effective_mineral_properties(
+    root_dir: Path, config: PemConfig, sim_init: SimInitProperties
+) -> Tuple[Union[np.ma.MaskedArray, None], MatrixProperties]:
+    """Estimate effective mineral properties for each grid cell
+
+    Args:
+        root_dir: start directory for running of PEM
+        config: configuration parameters
+        sim_init: simulation initial properties
+
+    Returns:
+        shale volume, effective mineral properties
+    """
+    if config.rock_matrix.volume_fractions.mode == VolumeFractions.NTG_SIM:
+        # ntg_from_init_file flag takes precedence over ntg_from_porosity
+        if config.rock_matrix.volume_fractions.from_porosity:
+            vsh = calc_ntg_from_porosity(sim_init.poro)
+        else:
+            vsh = ntg_to_shale_fraction(sim_init.ntg, sim_init.poro)
+        fractions = [
+            vsh,
+        ]
+    else:
+        fractions = import_fractions(root_dir, config)
+        # In case of a single fraction: it can either be NTG or a true volume fraction
+        if len(fractions) == 1 and config.rock_matrix.volume_fractions.fraction_is_ntg:
+            fractions[0] = ntg_to_shale_fraction(fractions[0], sim_init.poro)
+        vsh = get_shale_fraction(
+            fractions,
+            config.rock_matrix.fraction_names,
+            config.rock_matrix.shale_fractions,
+        )
+
+    mineral_names = config.rock_matrix.fraction_minerals
+    eff_min_props = estimate_effective_mineral_properties(
+        mineral_names, fractions, config
+    )
+    return vsh, eff_min_props
+
+
+def estimate_effective_mineral_properties(
+    fraction_names: Union[str, List[str]],
+    fractions: Union[np.ma.MaskedArray, List[np.ma.MaskedArray]],
+    pem_config: PemConfig,
+) -> MatrixProperties:
+    """Estimation of effective mineral properties must be able to handle cases where
+    there is a more complex combination of minerals than the standard sand/shale case.
+    For carbonates the input can be based on minerals (e.g. calcite, dolomite, quartz,
+    smectite, ...) or PRTs (petrophysical rock types) that each have been assigned
+    elastic properties to.
+    The rock physics library is aimed at one-dimensional arrays, not masked arrays, so
+    special handling of input objects is needed.
+
+    Args:
+        fraction_names: mineral names of the different fractions.
+        fractions: fraction of each mineral
+        pem_config: parameter object
+
+    Returns:
+        bulk modulus [Pa], shear modulus [Pa] and density [kg/m3] of effective mineral
+    """
+    verify_mineral_inputs(
+        fraction_names,
+        fractions,
+        pem_config.rock_matrix.minerals,
+        pem_config.rock_matrix.complement,
+    )
+
+    fraction_names, fractions = normalize_mineral_fractions(
+        fraction_names, fractions, pem_config.rock_matrix.complement
+    )
+
+    mask, *fractions = filter_and_one_dim(*fractions)
+    k_list = []
+    mu_list = []
+    rho_list = []
+    for name in fraction_names:
+        mineral = pem_config.rock_matrix.minerals[name]
+        k_list.append(to_masked_array(mineral.bulk_modulus, fractions[0]))
+        mu_list.append(to_masked_array(mineral.shear_modulus, fractions[0]))
+        rho_list.append(to_masked_array(mineral.density, fractions[0]))
+
+    if pem_config.rock_matrix.mineral_mix_model == MineralMixModel.HASHIN_SHTRIKMAN:
+        eff_k, eff_mu = multi_hashin_shtrikman(
+            *[arr for prop in zip(k_list, mu_list, fractions) for arr in prop]
+        )
+    else:
+        eff_k, eff_mu = multi_voigt_reuss_hill(
+            *[arr for prop in zip(k_list, mu_list, fractions) for arr in prop]
+        )
+    # Use phi masked array to restore original shape
+    eff_rho: np.ma.MaskedArray = np.ma.MaskedArray(
+        sum(rho * frac for rho, frac in zip(rho_list, fractions))
+    )
+    eff_min_k, eff_min_mu, eff_min_rho = reverse_filter_and_restore(
+        mask, eff_k, eff_mu, eff_rho
+    )
+    return MatrixProperties(
+        bulk_modulus=eff_min_k, shear_modulus=eff_min_mu, dens=eff_min_rho
+    )
+
+
+def verify_mineral_inputs(
+    names: str | list[str],
+    fracs: np.ma.MaskedArray | list[np.ma.MaskedArray],
+    minerals: dict[str, MineralProperties],
+    complement: str,
+) -> None:
+    if isinstance(names, str):
+        names = [names]
+
+    if isinstance(fracs, np.ma.MaskedArray):
+        fracs = [fracs]
+
+    if len(names) != len(fracs):
+        raise ValueError(
+            f"mismatch between number of mineral names and fractions, "
+            f"{len(names)} vs. {len(fracs)}"
+        )
+
+    for name in names + [complement]:
+        if name not in minerals:
+            raise ValueError(f"mineral names not listed in config file: {name}")
+
+
+def normalize_mineral_fractions(
+    names: str | list[str],
+    fracs: np.ma.MaskedArray | list[np.ma.MaskedArray],
+    complement: str,
+) -> Tuple[list[str], list[np.ma.MaskedArray]]:
+    """Normalizes mineral fractions and adds complement mineral if needed.
+
+    When the sum of specified mineral fractions is less than 1.0, adds the complement
+    mineral to make up the remainder. For example, if shale is 0.6 (60%) and the
+    complement mineral is quartz, then quartz will be added at 0.4 (40%) to reach 100%.
+
+    If fractions exceed valid range (0-1), they are clipped. If total exceeds 1.0,
+    all fractions are scaled down proportionally.
+
+    Args:
+        names: Single mineral name or list of mineral names
+        fracs: Single masked array or list of masked arrays containing mineral fractions
+        complement: Name of mineral to use as complement if sum < 1.0
+
+    Returns:
+        Tuple containing:
+            - List of mineral names (with complement added if needed)
+            - List of normalized mineral fractions as masked arrays
+    """
+    if isinstance(names, str):
+        names = [names]
+
+    if isinstance(fracs, np.ma.MaskedArray):
+        fracs = [fracs]
+
+    for i, frac in enumerate(fracs):
+        if np.any(frac[~frac.mask] < 0.0) or np.any(frac[~frac.mask] > 1.0):
+            warn(
+                f"mineral fraction {names[i]} has values outside of range 0.0 to 1.0,"
+                f"clipped to range",
+                UserWarning,
+            )
+            fracs[i] = np.ma.MaskedArray(np.ma.clip(frac, 0.0, 1.0))
+
+    tot_fractions = np.ma.sum(fracs, axis=0)
+    max_fraction = np.ma.max(tot_fractions)
+    TOLERANCE = 0.00001
+
+    if np.any(tot_fractions[~tot_fractions.mask] > 1.0 + TOLERANCE):
+        warn(
+            f"sum of mineral fractions are above 1.0 for "
+            f"{np.sum(tot_fractions[~tot_fractions.mask] > 1.0)} cells, is "
+            f"scaled to maximum 1.0.\n"
+            f"Max value is {np.max(tot_fractions[~tot_fractions.mask])}",
+            UserWarning,
+        )
+        for i, frac in enumerate(fracs):
+            fracs[i] /= max_fraction
+
+    comp_fraction = 1.0 - np.ma.sum(fracs, axis=0)
+    if np.any(comp_fraction > 0.0):
+        names = names + [complement]
+        fracs = fracs + [comp_fraction]
+
+    return names, fracs
+
+
+def calc_ntg_from_porosity(porosity: np.ma.MaskedArray) -> np.ma.MaskedArray:
+    vsh = to_masked_array(0, porosity)
+    vsh[porosity <= 0.33] = np.ma.power((0.33 - porosity[porosity < 0.33]) / 0.33, 2.0)
+    return (vsh / (1.0 - porosity)).clip(0.0, 1.0)