OilfieldToolsNet/opm-simulators
4
0
Fork 0
mirror of https://github.com/OPM/opm-simulators.git synced 2024-11-25 18:50:19 -06:00
Code Issues Packages Projects Releases Wiki Activity

handbook: work on the fluid framework chapter

Browse Source 
TODO: section on constraint solvers.
This commit is contained in:
Andreas Lauser 2012-02-06 17:47:48 +00:00 committed by Andreas Lauser
parent 9942e2604f
commit a159e40af1
2 changed files with 354 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/handbook/dumux-handbook.tex
View File

@ -61,6 +61,10 @@
\newcommand{\Dune}{{DUNE}\xspace}
\newcommand{\Dumux}{DuMu$^\text{x}$\xspace}
\newcommand{\porosity}{\phi}
\newcommand{\saturation}{S}
\newcommand{\doxyref}[3]{\textnormal{#1}}
\newenvironment{CompactList}
{\begin{list}{}{
@ -146,6 +150,7 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\input{structure}
\input{designpatterns}
\input{propertysystem}
\input{fluidframework}
\input{models}
\input{DumuxFlow}
\input{NewtonInANutshell}

353
doc/handbook/fluidframework.tex
View File

@ -10,10 +10,355 @@ the concepts is given, then a few implementation details follow.
\section{Overview of the Fluid Framework}
The fundamental concepts of the \Dumux fluid framwork are fluid
systems and fluid states. Fluid states are responsible for expressing
the complete thermodynamic configuration of a system, while fluid
systems are state-less classes which provide the relations that
The \Dumux fluid framework currently featurs the following concepts
(listed roughly in their order of importance):
\begin{description}
\item[Fluid state:] Fluid states are responsible for representing the
complete thermodynamic configuration of a system. A fluid state
always provides access methods to {\bf all} thermodynamic
quantities, but the concept of a does not mandate what assumptions
are made to store these thermodynamic quantities. What fluid states
do {\bf not} do is to make sure that the thermodynamic state which
they represent is physically possible.
\item[Fluid system:] Fluid systems express the thermodynamic {\bf
relations}\footnote{Strictly speaking, these relations are
functions, mathematically.} between quantities. Since functions do
not exhibit any internal state, all fluid systems are state-less
classes, i.e. all member functions are \texttt{static}. The
thermodynamic state is captured by a fluid state!
\item[Parameter cache:] Since fluid systems sometimes require
computationally expensive parameters for multiple relations, these
parameters can be cached using a so-called parameter
cache. Parameter cache objects are specfic for each fluid system but
they must provide a common interface to specify which quantities
changed since the last invocation.
\item[Constraint solver:] Constraint solvers are auxiliary tools to
make sure that a fluid state adheres to some thermodynamic
constraints. All constraint solvers specify a well defined set of
input variables make sure that the resulting fluid state is
consistent with a set of well-defined thermodynamic equations. See
section \ref{sec:constraint_solvers} for a detailed description of
the constraint solvers which are currently available in \Dumux.
\item[Equation of state:] Equations of state (EOS) are auxiliary
classes which provide relations between a fluid phase's temperature,
pressure and density. Since these classes are only used internally
in the fluid systems, the classes for a EOS are ad-hoc and there is
currently no common interface for them.
\item[Component:] Components are fluid systems which provide the
thermodynamic relations for the liquid and gas phase of a single
chemical species or a fixed mixture of species. Their main purpose
is to provide a convenient way to access these quantities from
full-fledged fluid systems, but they are not supposed to be used by
models directly.
\item[Binary coefficient:] Binary coefficients express the relations
of a mixture of two components. Typical binary coefficients are
\textsc{Henry} coefficients or binary molecular diffusion
coefficients. So far, the programming interface for accessing binary
coefficients has not been standardized.
\end{description}
\section{Fluid States}
{\bf All} fluid states {\bf must} export the following constants:
\begin{description}
\item[\texttt{numPhases}:] The number of fluid phases considered.
\item[\texttt{numComponents}:] The number of considered chemical
species or pseudo-species.
\end{description}
Also, {\bf all} fluid states {\bf must} provide the following methods:
\begin{description}
\item[\texttt{temperature()}:] The absolute temperature $T_\alpha$ of
a fluid phase $\alpha$.
\item[\texttt{pressure()}:] The absolute pressure $p_\alpha$ of a
fluid phase $\alpha$.
\item[\texttt{saturation()}:] The saturation $S_\alpha$ of a fluid
phase $\alpha$. The saturation is defined as the pore space occupied by the
fluid divided by the total pore space:
\[
\saturation_\alpha := \frac{\porosity \mathcal{V}_\alpha}{\porosity \mathcal{V}}
\]
\item[\texttt{moleFraction()}:] Returns the molar fraction
$x^\kappa_\alpha$ of a component $\kappa$ in a fluid phase
$\alpha$. The molar fraction $x^\kappa_\alpha$ is defined as the number
of molecules of a component in a mixture divided by the total number
of molecules in the fluid.
\item[\texttt{moleFraction()}:] Returns the mass fraction
$X^\kappa_\alpha$ of a component $\kappa$ in a fluid phase
$\alpha$. The mass fraction $X^\kappa_\alpha$ is defined as the
weight of a component in a mixture divided by the total mass of the
fluid. It is related with the component's mole fraction by means of
the relation
\[
X^\kappa_\alpha = x^\kappa_\alpha \frac{M^\kappa}{\overline M_\alpha}\;,
\]
where $M^\kappa$ is the molar mass of component $\kappa$ and
$\overline M_\alpha$ is the mean molar mass of a molecule of phase
$\alpha$.
\item[\texttt{averageMolarMass()}:] Returns $\overline M_\alpha$, the
mean molar mass of a molecule of phase $\alpha$. For a mixure of $N
> 0$ components, $\overline M_\alpha$ is defined as
\[
\overline M_\alpha = \sum_{\kappa=1}^{N} x^\kappa_\alpha M^\kappa
\]
\item[\texttt{density()}:] Returns the density $\rho_\alpha$ of a
fluid phase $\alpha$.
\item[\texttt{molarDensity()}:] Returns the molar density
$\rho_{mol,\alpha}$ of a fluid phase $\alpha$. The molar density can
be defined using the mass density $\rho_\alpha$ and the mean molar mass $\overline M_\alpha$ by
\[
\rho_{mol,\alpha} = \frac{\rho_\alpha}{\overline M_\alpha} \;.
\]
\item[\texttt{molarVolume()}:] Returns the molar volume
$V_{mol,\alpha}$ of a fluid phase $\alpha$. This quantity is just
the inverse of the molar density.
\item[\texttt{molarity()}:] Returns the molar concentration
$c^\kappa_\alpha$ of component $\kappa$ in fluid
phase $\alpha$.
\item[\texttt{fugacity()}:] Returns the fugacity $f^\kappa_\alpha$ of
component $\kappa$ in fluid phase $\alpha$. The fugacity is defined
as
\[
f_\alpha^\kappa := \Phi^\kappa_\alpha x^\kappa_\alpha p_\alpha \;,
\]
where $\Phi^\kappa_\alpha$ is the {\em fugacity coefficient}. The
physical meaning of fugacity becomes clear from the equation
\[
f_\alpha^\kappa = p_\alpha \exp\left\{\frac{\zeta^\kappa_\alpha}{R T_\alpha} \right\} \;,
% TODO: cite
\]
where $\zeta^\kappa_\alpha$ represents the $\kappa$'s chemical
potential in phase $\alpha$, $R$ stands for the
ideal gas constant, and $T_\alpha$ for the absolute
temperature phase $\alpha$. Assuming thermal equilibrium, there is a
one-to-one mapping between a component's chemical potential
$\zeta^\kappa_\alpha$ and its fugacity $f^\kappa_\alpha$. In this
case chemical equilibrium can thus be expressed by
\[
f^\kappa = f^\kappa_\alpha = f^\kappa_\beta \forall \alpha, \beta
\]
\item[\texttt{fugacityCoefficient()}:] Returns the fugacity coefficient $\Phi^\kappa_\alpha$ of
component $\kappa$ in fluid phase $\alpha$.
\item[\texttt{enthalpy()}:] Returns specific enthalpy $h_\alpha$ of a
fluid phase $\alpha$.
\item[\texttt{internalEnergy()}:] Returns specific internal energy $u_\alpha$ of a
fluid phase $\alpha$. The specific internal energy is defined by the relation
\[
u_\alpha = h_\alpha - \frac{p_\alpha}{\rho_\alpha}
\]
\item[\texttt{viscosity()}:] Returns the dynamic viscosity
$\mu_\alpha$ of fluid phase $\alpha$.
\end{description}
Currently, the following fluid states are available in \Dumux:
\begin{description}
\item[\texttt{NonEquilibriumFluidState}:] This is the most general
fluid state supplied. It does not assume thermodynamic equilibrium
and this stores all phase compositions (using mole fractions) and
fugacity coefficients, as well as all phase temperatures, pressures,
saturations and enthalpies.
\item[\texttt{CompositionalFluidState}:] The
\texttt{NonEquilibriumFluidState} with the difference
\texttt{CompositionalFluidState} is similar to the difference that
is assumes thermodynamic equilibrium. In the context of multi-phase
flow in porous media, this means that only a single temperature
needs to be stored.
\item[\texttt{ImmisicibleFluidState}:] This fluid state assumes that
the fluid phases are immiscible, which implies that the phase
compositions and the fugacity coefficients do not need to be stored
explicitly.
\item[\texttt{PressureOverlayFluidState}:] This is a so-called {\em
overlay} fluid state. It allows to set the pressure of all fluid
phases but forwards everything else to an other fluid state.
\item[\texttt{SaturationOverlayFluidState}:] This fluid state is like
the \texttt{PressureOverlayFluidState}, except that the phase
saturations are settable instead of the phase pressures.
\item[\texttt{TempeatureOverlayFluidState}:] This fluid state is like
the \texttt{PressureOverlayFluidState}, except that the temperature
is settable instead of the phase pressures. Note that this overlay
state assumes thermal equilibrium regardless of underlying fluid
state.
\item[\texttt{CompositionOverlayFluidState}:] This fluid state is like
the \texttt{PressureOverlayFluidState}, except that the phase
composition is settable (in terms of mole fractions) instead of the
phase pressures.
\end{description}
\section{Fluid Systems}
\subsection{Parameter Caches}
All fluid systems must export a type for their \texttt{Parameter}
cache objects. For fluid systems which do not require to cache
parameters, \Dumux provides a \texttt{NullParameterCache} class.
Parameter caches must at least provide the following methods
\begin{description}
\item[updateAll(fluidState, except):] Update all cached quantities in
all phases. The \texttt{except} argument contains a bitfield of the
quantities which have not changed since the last call to a
\texttt{update()} method.
\item[updateAllPresures(fluidState):]
Update all cached quantities which depend on pressure for
all phases.
\item[updateAllTemperatures(fluidState):]
Update all cached quantities which depend on temperature for
all phases.
\item[updatePhase(fluidState, phaseIdx, except):] Update all cached
quantities for a given phase. The quantities specified by the
\texttt{except} bitfield have not been modified since the last
call to an \texttt{update()} method.
\item[updateTemperature(fluidState, phaseIdx):] Update all cached
quantities which depend on the temperature of a given phase.
\item[updatePressure(fluidState, phaseIdx):] Update all cached
quantities which depend on the pressure of a given phase.
\item[updateComposition(fluidState, phaseIdx):] Update all cached
quantities which depend on the composition of a given phase.
\item[updateSingleMoleFraction(fluidState, phaseIdx, compIdx):]
Update all cached quantities which depend on the value of a mole
fraction of a given components of a given phase.
\end{description}
Note, that the parameter cache interface only guarantees that if a
more specialized \texttt{update()} method is called, it is not slower
than the next more-general method (e.g. calling
\texttt{updateSingleMoleFraction()} can be as expensive as
\texttt{updateAll()}). It is thus advisable to rather use a broader
\texttt{update()} method than more than one calls to specialized
\texttt{update()} methods.
To make usage of parameter caches easier for the case where all cached
quantities ought to be re-calculated if the respective phase was
changed, it is possible to just define the \texttt{updatePhase()} and
derive a parameter cache from \texttt{Dumux::ParameterCacheBase}.
\subsection{Exported Constants and Capabilities}
Besides providing the type of their \texttt{ParameterCache} objects,
fluid systems need to export the following constants:
\begin{description}
\item[\texttt{numPhases}:] The number of considered fluid phases.
\item[\texttt{numComponents}:] The number of considered chemical (pseudo-) species.
\item[\texttt{phaseName()}:] Given the index of a fluid phase, return a
human-readable string as its name.
\item[\texttt{componentName()}:] Given the index of a component,
return a human-readable string as its name.
\item[\texttt{isLiquid()}:] Return whether the phase is a liquid, given the index of a phase.
\item[\texttt{isIdealMixture()}:] Return whether the phase is an ideal
mixture, given the index of a phase. In the context of the \Dumux
fluid framework a phase $\alpha$ is an ideal mixture if, and only if
all its fugacity coefficients $\Phi^\kappa_\alpha$ do not depend on
the phase composition. (Although they might very well depend on
temperature and pressure.)
\item[\texttt{isIdealGas()}:] Return whether a phase $\alpha$ is an ideal
gas, i.e. it adheres to the relation
\[
p_\alpha V_{mol,\alpha} = R T_\alpha \;,
\]
with $R$ being the ideal gas constant.
\item[\texttt{isCompressible()}:] Return whether a phase $\alpha$ is
compressible, i.e. its density depends on pressure $p_\alpha$.
\item[\texttt{molarMass()}:] Given a component index, return the molar
mass of the corresponding component.
\end{description}
\subsection{Thermodynamic Relations}
Fluid systems have been explicitly designed to provide as few
thermodynamic relations as possible. A full-fledged fluid system thus
only needs to provide the following methods:
\begin{description}
\item[\texttt{init()}:] Initialize the fluid system. This is usually
used tabulated to tabulate some quantites
\item[\texttt{density()}:] Given a fluid state, an up-to-date parameter
cache and a phase index, return the density of the phase.
\item[\texttt{fugacityCoefficient}:] Given a fluid state, an up-to-date
parameter cache as well as a phase and a component index, return the
fugacity coefficient of a the component for the phase.
\item[\texttt{viscosity()}:] Given a fluid state, an up-to-date parameter
cache and a phase index, return the dynamic viscosity of the phase.
\item[\texttt{diffusionCoefficient}:] Given a fluid state, an
up-to-date parameter cache and a phase index, return the dynamic
viscosity of the phase, calculate the molecular diffusion
coefficient for a component in a fluid phase
Molecular diffusion of a component $\kappa$ in phase $\alpha$ is
caused by a gradient of the chemical potential and follows the law
\[
J^\kappa_\alpha = - D\ \mathbf{grad} \zeta^\kappa_\alpha\;,
\]
where $\zeta^\kappa_\alpha$ is the component's chemical potential,
$D$ is the diffusion coefficient and $J^\kappa_\alpha$ is the
diffusive flux. $\zeta^\kappa_\alpha$ is connected to the
component's fugacity $f^\kappa_\alpha$ by the relation
\[
\zeta^\kappa_\alpha =
R T_\alpha \mathrm{ln} \frac{f^\kappa_\alpha}{p_\alpha} \;.
\]
\item[\texttt{binaryDiffusionCoefficient}:] Given a fluid state, an
up-to-date parameter cache, a phase index and two
component indices return the binary diffusion coefficient for
components for the binary mixture. This method is less general than
\texttt{diffusionCoefficient} method, but usually only binary
diffusion coefficients can be found in the literature.
\item[\texttt{enthalpy}:] Given a fluid state, an up-to-date parameter
cache and a phase index, this method represents the specific
enthalpy $h_\alpha$ of the phase.
\item[\texttt{thermalConductivity}:] Given a fluid state, an
up-to-date parameter cache and a phase index, this method represents
the thermal conductivity of the fluid phase.
\item[\texttt{heatCapacity}:] Given a fluid state, an up-to-date
parameter cache and a phase index, this method represents the
isobaric heat capacity $c_{p,\alpha}$ of the fluid phase. The
isobaric heat capacity is defined as the partial derivative of the
specific enthalpy $h_\alpha$ to the fluid pressure:
\[
c_{p,\alpha} = \frac{\partial h_\alpha}{\partial p_\alpha}
\]
\end{description}
Fluid systems may chose not to implement some of these methods and
throw a \texttt{Dune::NotImplemented} exception instead. Obviously,
such fluid systems cannot be used in conjunction with models that
depend on those methods.
\subsection{Available Fluid Systems}
Currently, the following fluid states are available in \Dumux:
\begin{description}
\item[\texttt{Dumux::FluidSystems::TwoPImmiscible}:] A two-phase fluid
system featuring which assumes immiscibility of the fluid
phases. The fluid phases are thus specified by means of their
constituting components. This fluid system is intented to be used
with models that assume immiscibility.
\item[\texttt{Dumux::FluidSystems::H2ON2}:] A two-phase fluid system
featuring the gas and liquid phases and destilled water ($H_2O$) and
pure molecular Nitrogen ($N_2$) as components.
\item[\texttt{Dumux::FluidSystems::H2OAir}:] A two-phase fluid system
featuring the gas and liquid phases and destilled water ($H_2O$) and
air (Pseudo component composed of $79\%\;N_2$, $20\%\;O_2$ and
$1\%\;Ar$) as components.
\item[\texttt{Dumux::FluidSystems::H2OAirMesitylene}:] A three-phase fluid
system featuring the gas, NAPL and water phases and destilled water
($H_2O$) and air and Mesitylene ($C_6H_3(CH_3)_3$) as components. This fluid
system assumes all phases to be ideal mixtures.
\item[\texttt{Dumux::FluidSystems::H2OAirXylene}:] A three-phase fluid
system featuring the gas, NAPL and water phases and destilled water
($H_2O$) and air and Xylene ($C_8H_{10}$) as components. This fluid
system assumes all phases to be ideal mixtures.
\item[\texttt{Dumux::FluidSystems::Spe5}:] A three-phase fluid system
featuring the gas, oil and water as phases and the seven components
distilled water ($H_2O$), Methane ($C_1$), Propane ($C_3$), Pentane
($C_5$), Heptane ($C_7$), Decane ($C_{10}$), Pentadecane
($C_{15}$) and Icosane ($C_{20}$). For the water phase the IAPWS-97
formulation is used as equation of state, while for the gas and oil
phases a \textsc{Peng}-\textsc{Robinson} equation of state with
slightly modified parameters is used. This fluid system is highly
non-linear, and the gas and oil phases can also not be considered as
ideal mixtures. % TODO: citation
\end{description}
\section{Constraint Solvers}
\label{sec:constraint_solvers}
%%% Local Variables:
%%% mode: latex