Tutorial fluid modelling

src/porepy/compositional/base.py

@@ -48,7 +48,7 @@
 
 from __future__ import annotations
 
-from typing import Generator, Generic, Sequence, TypeVar
+from typing import Generator, Generic, Optional, Sequence, TypeVar
 
 import numpy as np
 
@@ -455,26 +455,29 @@ class Phase(Generic[ComponentLike]):
         created by normalization of fractions in :attr:`extended_fraction_of`.
 
         If the flow & transport model does not include an equilibrium formulation,
-        the extended fractions are meaningless and the partialf ractions are independent
+        the extended fractions are meaningless and the partial fractions are independent
         variables instead.
 
     The class supports some generic typing to narrow down the type of components
     contained within the class, e.g. ``phase: Phase[FluidComponent] = Phase(...)``.
 
     Parameters:
-        eos: An EoS which provides means to compute physical properties of the phase.
-            Can be different for different phases.
         state: The physical state this phase represents.
         name: Given name for this phase. Used as an unique identifier and for naming
             various variables and properties.
+        eos: ``default=None``
+
+            An EoS which provides means to compute physical properties of the phase.
+            Can be different for different phases, or None if no external computations
+            are used.
 
     """
 
     def __init__(
         self,
-        eos: EquationOfState,
         state: PhysicalState,
         name: str,
+        eos: Optional[EquationOfState] = None,
     ) -> None:
         self._ref_component_index: int = 0
         """See :meth:`reference_component_index`."""
@@ -487,11 +490,11 @@ def __init__(
         To be set by the user, or by some instance of
         :class:`~porepy.compositional.compositional_mixins.FluidMixin`
 
-        Once set, it should not be modified. Avoid multiple occurences of components.
+        Once set, it should not be modified. Avoid multiple occurrences of components.
 
         """
 
-        self.eos: EquationOfState = eos
+        self.eos: Optional[EquationOfState] = eos
         """The EoS passed at instantiation."""
 
         self.state: PhysicalState = state
@@ -540,7 +543,7 @@ def __init__(
         """
 
         self.fugacity_coefficient_of: dict[Component, ExtendedDomainFunctionType]
-        """Fugacitiy coefficients per component in this phase.
+        """Fugacity coefficients per component in this phase.
 
         Dimensionless, scalar field.
 
@@ -670,8 +673,19 @@ def reference_component(self) -> ComponentLike:
     def compute_properties(self, *thermodynamic_input: np.ndarray) -> PhaseProperties:
         """Shortcut to compute the properties calling
         :meth:`EquationOfState.compute_phase_state` of :attr:`eos` with :attr:`state` as
-        argument."""
-        return self.eos.compute_phase_properties(self.state, *thermodynamic_input)
+        argument.
+
+        Raises:
+            CompositionalModellingError: If this phase has no EoS assigned.
+
+        """
+        if isinstance(self.eos, EquationOfState):
+            return self.eos.compute_phase_properties(self.state, *thermodynamic_input)
+        else:
+            raise CompositionalModellingError(
+                f"Phase ({self.state, self.name}) has no EoS assigned for computing "
+                + "phase properties."
+            )
 
 
 PhaseLike = TypeVar("PhaseLike", bound=Phase, covariant=True)
@@ -684,7 +698,7 @@ class Fluid(Generic[ComponentLike, PhaseLike]):
     The fluid (mixture) serves as a container for components and phases and contains the
     specification of the reference component and phase.
 
-    It also provides general attributes for some thermodynamic properites of a fluid,
+    It also provides general attributes for some thermodynamic properties of a fluid,
     which are required by the remaining framework. Hence this class serves as an
     interface for e.g. PDE formulations.
 

src/porepy/compositional/compositional_mixins.py

@@ -1107,8 +1107,25 @@ def create_fluid(self) -> None:
         components: list[pp.FluidComponent] = [c for c in self.get_components()]
 
         for config in self.get_phase_configuration(components):
-            eos, type_, name = config
-            phases.append(Phase(eos, type_, name))
+            # Configuration of phase with EoS.
+            if len(config) == 3:
+                phase_state, name, eos = config
+                assert isinstance(eos, EquationOfState), (
+                    f"Expecting an instance of `EquationOfState`, got {type(eos)}."
+                )
+            # Configuration of phase without EoS.
+            elif len(config) == 2:
+                phase_state, name = config
+                eos = None
+
+            assert phase_state in PhysicalState, (
+                f"Expecting a valid `PhysicalState`, got {phase_state}."
+            )
+            assert isinstance(name, str), (
+                f"Expecting a string as name for phase, got {type(name)}."
+            )
+
+            phases.append(Phase(phase_state, name, eos=eos))
 
         self.set_components_in_phases(components, phases)
 
@@ -1138,12 +1155,14 @@ def get_components(self) -> Sequence[pp.FluidComponent]:
 
     def get_phase_configuration(
         self, components: Sequence[ComponentLike]
-    ) -> Sequence[tuple[EquationOfState, PhysicalState, str]]:
+    ) -> Sequence[
+        tuple[PhysicalState, str] | tuple[PhysicalState, str, EquationOfState]
+    ]:
         """Method to return a configuration of modelled phases.
 
-        The default implementation returns a liquid-like phase with an abstract EoS
-        instance (to be used in the standard set-up with heuristic fluid properties
-        implemented for 1-phase fluids).
+        The default implementation returns a liquid-like phase named ``'liquid'``
+        (to be used in the standard set-up with heuristic fluid properties implemented
+        for 1-phase fluids).
 
         Parameters:
             components: The list of components modelled by :meth:`get_components`.
@@ -1154,18 +1173,21 @@ def get_phase_configuration(
                     The user can use only a single EoS instance for all phases f.e.
 
         Returns:
-            A sequence of 3-tuples containing
+            A sequence of 2-tuples or 3-tuples containing
 
-            1. An instance of an EoS.
-            2. The phase state.
-            3. A name for the phase.
+            1. The phase state.
+            2. A name for the phase.
+            3. (optional) An instance of an EoS.
 
             Each tuple will be used to create a phase in the fluid mixture.
             For more information on the required return values see
             :class:`~porepy.compositional.base.Phase`.
 
+            Phase configurations which do not return an EoS are assumed to use
+            heuristics.
+
         """
-        return [(EquationOfState(components), PhysicalState.liquid, "liquid")]
+        return [(PhysicalState.liquid, "liquid")]
 
     def set_components_in_phases(
         self, components: Sequence[Component], phases: Sequence[Phase]

src/porepy/models/fluid_property_library.py

@@ -1,4 +1,4 @@
-""" "Module containing some constant heuristic fluid property implementations and
+"""Module containing some constant heuristic fluid property implementations and
 the mixin :class:`FluidMobility`, which is required in all flow & transport problems.
 
 Most of the laws implemented here are meant for 1-phase, 1-component mixtures, using
@@ -67,7 +67,7 @@ def fluid_compressibility(self, subdomains: Sequence[pp.Grid]) -> pp.ad.Operator
         )
 
     def density_of_phase(self, phase: pp.Phase) -> ExtendedDomainFunctionType:
-        """ "Mixin method for :class:`~porepy.compositional.compositional_mixins.
+        """Mixin method for :class:`~porepy.compositional.compositional_mixins.
         FluidMixin` to provide a density exponential law for the fluid's phase.
 
         .. math::
@@ -139,7 +139,7 @@ def fluid_thermal_expansion(self, subdomains: Sequence[pp.Grid]) -> pp.ad.Operat
         return Scalar(val, "fluid_thermal_expansion")
 
     def density_of_phase(self, phase: pp.Phase) -> ExtendedDomainFunctionType:
-        """ "Analogous to :meth:`FluidDensityFromPressure.density_of_phase`, but using
+        """Analogous to :meth:`FluidDensityFromPressure.density_of_phase`, but using
         temperature and the thermal expansion of the reference component.
 
         .. math::

tests/compositional/test_fluid_mixtures.py

@@ -145,7 +145,7 @@ def test_mixture_contexts(
             if has_gas:
                 has_more_gas = True
             has_gas = True
-        phases.append(compositional.Phase(eos, t, name))
+        phases.append(compositional.Phase(t, name, eos=eos))
         phases[-1].components = [h2o] + components  # to avoid errors
 
     phasenames = [phase.name for phase in phases]
@@ -209,8 +209,8 @@ def test_mixture_member_assignment(
     # dummy EoS for completeness
     eos = compositional.EquationOfState([comp1, comp2])
     phases = [
-        (eos, compositional.PhysicalState.liquid, "L"),
-        (eos, compositional.PhysicalState.gas, "G"),
+        (compositional.PhysicalState.liquid, "L", eos),
+        (compositional.PhysicalState.gas, "G", eos),
     ]
 
     model: MockModel = get_mock_model(
@@ -482,7 +482,7 @@ def test_singular_mixtures(species, phase_names, equilibrium_type):
     hash(components[0])
 
     eos = compositional.EquationOfState(components)
-    phases = [(eos, compositional.PhysicalState.liquid, name) for name in phase_names]
+    phases = [(compositional.PhysicalState.liquid, name, eos) for name in phase_names]
 
     model: MockModel = get_mock_model(components, phases, True, equilibrium_type)
 

tests/functional/setups/linear_tracer.py

@@ -649,7 +649,7 @@ def get_phase_configuration(
         """Returns configs for 3 phases with same dummy EoS."""
         eos = TrivialEoS(components)
         state = pp.compositional.PhysicalState.liquid
-        return [(eos, state, "1"), (eos, state, "2"), (eos, state, "3")]
+        return [(state, "1", eos), (state, "2", eos), (state, "3", eos)]
 
     def dependencies_of_phase_properties(
         self, phase: pp.Phase

tests/numerics/test_time_step_control.py

@@ -488,7 +488,7 @@ def test_non_recomputed_solution_conditions(self):
         assert time_manager._recomp_sol and (msg in str(excinfo.value))
 
     def test_recompute_solution_false_by_default(self):
-        """ "Checks if recompute solution is False by default"""
+        """Checks if recompute solution is False by default"""
         time_manager = pp.TimeManager([0, 1], 0.1)
         time_manager.compute_time_step(iterations=3)
         assert not time_manager._recomp_sol

tutorials/Readme.md

@@ -32,4 +32,5 @@ For the more experienced user, some more specific tutorials are also available:
 14. [Mandel's problem](./mandels_problem.ipynb) shows how to set up and run the Mandel's consolidation problem based on the Biot equations of poroelasticity. 
 15. [Flux discretizations](./flux_discretizations.ipynb) shows different discretization methods available for diffusive fluxes. These are used for Darcy's law for fluid fluxes in a mass balance equation.
 16. [Stress discretization](./stress_discretization.ipynb) describes the discretization method used for the vector version of tutorial #15, which arises in the linear elastisity equations.
-17. [Linear Tracer Flow](./tracer_flow.ipynb) describes the setup of a linear single-phase, 2-component model based on tutorial #6, and showcases a simulation of tracer transport through a fractured domain.
+17. [Linear Tracer Flow](./tracer_flow.ipynb) describes the setup of a linear single-phase, 2-component model based on tutorial #6, and showcases a simulation of tracer transport through a fractured domain.
+19 [Fluid modeling](./fluid_modeling.ipynb) explains how to set up multicomponent, multiphase fluids in a model, and various approaches to modeling fluid properties.