materialsystem.md

title: The DuMu^x^ Material System

Challenge

Flow in porous media

• Highly heterogeneous distribution of parameters and complex nonlinear material laws
• Strong interconnection of properties \rightarrow difficult to achieve modularity

\rightarrow this also applies to other complex nonlinear equation systems.

How to achieve modularity?

How to achieve modularity?

• User-defined parameters and functional relationships:
  • Components / Fluid system / Binary coefficients
  • Solid system
  • Fluid-matrix interactions
  • Chemistry
• State representations and solvers:
  • Fluid states (data)
  • Solid states (data)
  • Constraint solvers / "flash" (algorithm)

How to achieve modularity?

There is a library of Components, FluidSystems, BinaryCoefficients available in DuMu^x^. Can be used as is or can be a good start for a user implementation.

More resources can be found in the code documentation.

Components

Components

• Define thermodynamic relations (e.g. molar mass, vapor pressure, density) of a single chemical species or a fixed mixture of species
• Provide a convenient way to access these quantities

Example implementations

• H2O : pure water properties by IAPWS-97
• SimpleH2O : a simple water implementation at standard conditions
• Brine : water with a given salt concentration
• Many more, see DuMu^x^ components docs

Example interfaces

static Scalar gasDensity(Scalar temperature, Scalar pressure)
{
    // Assume an ideal gas
    return IdealGas::density(molarMass(), temperature, pressure);
}

Example interfaces

static Scalar gasHeatCapacity(Scalar temperature, Scalar pressure)
{
    constexpr Scalar cpVapA = 19.25;
    constexpr Scalar cpVapB = 0.05213;
    constexpr Scalar cpVapC = 1.197e-5;
    constexpr Scalar cpVapD = -1.132e-8;

    return 1/molarMass()*(
        cpVapA + temperature*(
            cpVapB/2 + temperature*(cpVapC/3 + temperature*(cpVapD/4))
        )
    );
}

Fluid systems

Fluid systems

Express the thermodynamic relations between fluid quantities (e.g. calculation of density or viscosity based on composition; fugacity coefficient based on temperature and pressure...)

Example implementations

• TwoPImmiscible : two immiscible fluid phases
• H2OAir : gas and liquid phase with components water and air
• Many more, see DuMu^x^ fluid systems docs

Example interface

template <class FluidState>
static Scalar heatCapacity(const FluidState& fluidState, int phaseIdx)
{
    const Scalar temperature = fluidState.temperature(phaseIdx);
    const Scalar pressure = fluidState.pressure(phaseIdx);
    if (phaseIdx == liquidPhaseIdx)
        return H2O::liquidHeatCapacity(temperature, pressure); // neglect air
    else if (phaseIdx == gasPhaseIdx)
        return Air::gasHeatCapacity(temperature, pressure)
                   * fluidState.moleFraction(gasPhaseIdx, AirIdx)
               + H2O::gasHeatCapacity(temperature, pressure)
                   * fluidState.moleFraction(gasPhaseIdx, H2OIdx);
    ...
}

Binary coefficients

Binary coefficients

Contain data and equations required for binary mixtures, for instance, binary diffusion coefficients or coefficients needed for constitutive relationships (e.g. Henry coefficient)

Example implementations

• H2O_Air : Henry coefficient, gas diffusion coefficient, liquid diffusion coefficent for water and air
• More, see DuMu^x^ binary coefficients docs

Example interface

template <class Scalar>
static Scalar gasDiffCoeff(Scalar temperature, Scalar pressure)
{
    // _H2O_Air_
    constexpr Scalar theta = 1.8;
    constexpr Scalar Daw = 2.13e-5;  /* reference value */
    constexpr Scalar pg0 = 1.e5;     /* reference pressure */
    constexpr Scalar T0 = 273.15;    /* reference temperature */
    using std::pow;
    return Daw*(pg0/pressure)*pow((temperature/T0), theta);
}

Solid systems

Solid systems

Express the thermodynamic properties of the solid matrix (e.g. calculation of the solid density and solid heat capacity based on the composition)

Specifying a solid system is only necessary if you work with a non-isothermal or mineralization model. If no solid system is specified in the problem file, the default is the inert solid phase with the constant component. For the constant component you can set properties in the input file.

Implementations

• OneCSolid : inert solid matrix of one solid component (e.g. granite)
• CompositionalSolidPhase : composed solid matrix of inert or reactive components (e.g. NaCl and granite)

Fluid-matrix interactions

Fluid-matrix interactions

• Description of the interaction of the fluid phases with the porous medium (e.g. capillary pressure-saturation and relative permeability relationships)
• Through modular adapters, regularization schemes can be imposed for extreme values

Example implementations

• Capillary pressure-saturation relation after Van Genuchten
• Capillary pressure-saturation relation after Brooks and Corey
• Effective diffusivity after Millington and Quirk

Van Genuchten

\begin{equation} p_c = \frac{1}{\alpha}\left(S_e^{-1/m} -1\right)^{1/n} \end{equation}

\rightarrow the empirical parameters \alpha and n have to be specified

Brooks-Corey

\begin{equation} p_c = p_d S_e^{-1/\lambda} \end{equation}

\rightarrow the empirical parameters p_d and \lambda have to be specified

Fluid states

Fluid states

• Store the complete thermodynamic configuration of a system at a given spatial and temporal position (e.g. saturation, mole fraction, enthalpy)
• Provide access methods to all thermodynamic quantities (e.g. saturation, mole fraction, enthalpy)

Example implementations

• ImmiscibleFluidState : assumes immiscibility of the fluid phases. Phase compositions and fugacity coefficients do not need to be stored explicitly.
• CompositionalFluidState : assumes thermodynamic equilibrium, only a single temperature needs to be stored.

Solid states

Solid states

• Store the complete solid configuration of a system at a given spatial and temporal position (e.g. solid volume fractions, solid heat capacity)
• Provide access methods to all solid quantities (e.g. porosity, density, temperature)

Example implementations

• InertSolidState : assumes an inert solid phase. Solid volume fractions do not change. This is the default.
• CompositionalSolidState : assumes a solid matrix composed out of multiple components. The volume fractions can change and properties such as heat capacity are adapted.

Constraint Solvers

Constraint solvers

Connect the thermodynamic relations expressed by fluid systems with the thermodynamic quantities stored by fluid states (e.g. mole fraction, density)

Example implementation

CompositionFromFugacities : takes all component fugacities, the temperature and pressure of a phase as input and calculates the phase composition

Example: From components to fluid system

Components \rightarrow fluid system

Example: 2 phases, miscible

• Components: H2O, Air
• Fluid system: TwoPTwoC

Relevant headers

// Predefined fluid system for components water and air
#include <dumux/material/fluidsystems/h2oair.hh>

// H2OAir allows to customize the water phase. Here, we want
// to use tabulated H2O for fast evaluation of the properties.
#include <dumux/material/components/h2o.hh>
#include <dumux/material/components/tabulatedcomponent.hh>

Setting the FluidSystem property

template<class TypeTag>
struct FluidSystem<TypeTag, TTag::H2OAir>
{
private:
    using Scalar = GetPropType<TypeTag, Properties::Scalar>;
    using Liquid = Components::TabulatedComponent<Components::H2O<Scalar>>;
    using Policy = FluidSystems::H2OAirDefaultPolicy<
        /*fastButSimplifiedRelations=*/true
    >;
public:
    using type = FluidSystems::H2OAir<
        Scalar, Liquid, Policy, /*useKelvinVapourPressure*/true
    >;
};

Example: From components to solid system

Example: 2 phases, miscible

• Components: CaO, CaO2H2 (slaked lime)
• Solid system: OnePNCMin

Specify solid system in properties file:

// The solid system
template<class TypeTag>
struct SolidSystem<TypeTag, TTag::ThermoChem>
{
    using Scalar = GetPropType<TypeTag, Properties::Scalar>;
    using ComponentOne = Components::ModifiedCaO<Scalar>;
    using ComponentTwo = Components::CaO2H2<Scalar>;
    using type = SolidSystems::CompositionalSolidPhase<
        Scalar, ComponentOne, ComponentTwo
    >;
};

Exercise

Tasks:

1. Get familiar with the code
2. 2p model: Implement a new component (incompressible and compressible)
3. 2p2c model: Implement a new fluid system
4. Change wettability of the porous medium
5. Advanced: Use van Genuchten relationship with parameters: \alpha = 0.0037 and \alpha_\mathrm{lense} = 0.00045, n = 4.7 and n_\mathrm{lense} = 7.3

First step:

Go to Fluidsystem exercise