initial.rst 5.06 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
Initial Conditions
==================

DORiE computes transient solutions, and hence needs a solution from which it
can start. There are multiple ways of specifying an initial condition.
All have in common that the data provided must be interpolated on the
respective solution grid function space. Depending on the actual input data,
this means that information can be lost and specific features can be distorted.
Users are responsible to ensure that the solution grid function space and the
input data for initial conditions match in this sense.

Initial conditions can generally be stated in several physical quantities, as
long as the respective quantity has a unique transformation to the solver
solution quantity.

Initial condition input is controlled entirely via the
17
:doc:`Configuration File <config-file>`.
18

19 20 21 22 23 24
.. note::
   The initial condition is projected onto the actual solution function space.
   Depending on grid shape and resolution, function space (order), and
   interpolator (if applicable), the resulting solution may vary greatly from
   the actual input data.

25 26 27 28 29
Input Types
-----------
This is an overview of all input types for initial conditions.
They are controlled by the ``initial.type`` key and available for every model.

30
.. object:: Analytic
31

32
    * ``type = analytic``
33

34 35
    An analytic function :math:`f(\mathbf{p})` which depends on the physical
    position :math:`\mathbf{p}`. The function must be defined via the key
36 37 38 39 40
    ``initial.equation``. For parsing the input expression, we use muparser_
    which supports a set of common mathematical functions. Additionally, the
    following variables can be used:

    Available variables:
41 42 43
      * ``x``: X-coordinate :math:`p_1 \, [\text{m}]`.
      * ``y``: Y-coordinate :math:`p_2 \, [\text{m}]`.
      * ``z``: Z-coordinate :math:`p_3 \, [\text{m}]` (only in 3D).
44 45 46 47 48 49 50
      * ``h``: Height above origin. Synonymous to ``y`` in 2D and ``z`` in 3D.
      * ``pi``: Mathematical constant :math:`\pi`.
      * ``dim``: Number of physical dimensions.

    .. tip::
       Assuming the target quantity is the matric head (see
       :ref:`initial-transformation`), typical initial conditions for a
51
       Richards model are
52

53 54 55
       * Hydrostatic equilibrium: A vertical gradient of
         :math:`\partial_h h_m = -1` and a fixed value ``<v>`` at height
         :math:`h = 0 \, \text{m}`:
56

57
            initial.equation = -h + <v>
58

59
       * Gravity flow: Constant value.
60

61 62
    .. tip::
       The expression for a gaussian pulse of solute concentration centered at
63 64
       :math:`\vec{p} = [0.5, 0.5]^T \, \mathrm{m}` and variance of
       :math:`\sigma^2 = \left( 0.1 \, \mathrm{m} \right)^2` is::
65

66 67 68 69
          initial.equation = <m> * exp(-((x-0.5)^2+(y-0.5)^2)/(2.*0.1^2)) / (2*pi*0.1^2)

       where ``<m>`` is the total solute mass of the pulse
       :math:`m_s \, [\text{kg}]`.
70

71
.. object:: Dataset
72 73 74

    * ``type = data``

75 76 77 78 79 80 81
    Load the initial condition from a data file ``initial.file`` by opening the
    dataset ``initial.dataset`` inside this file. The data is interpreted as
    function :math:`f(\mathbf{p})` of the physical position :math:`\mathbf{p}`
    using one of the available :ref:`interpolators <man-interpolators>`, which
    can be chosen using the setting ``initial.interpolation``. The input data
    is automatically streched to match the grid extensions.

82 83
    .. note:: For ``FEorder > 0``, linear interpolation is recommended.

84 85 86 87 88
    Supported file extensions:

    * ``.h5``: H5_ data file. ``initial.dataset`` may be a file-internal path
      to the target dataset.

89
.. _initial-transformation:
90

91 92 93 94 95 96 97 98 99 100 101 102 103 104
Transformation Types
--------------------
This is an overview of the transformation types of all models.
They are controlled via the ``initial.quantity`` key.

Richards
^^^^^^^^
Initial condition tranformations for the Richards solver.

.. object:: No Transformation

    * ``quantity = matricHead``

    The input data is directly interpreted as matric head
105
    :math:`f = h_m \, [\text{m}]`.
106 107 108 109 110 111

.. object:: Water Content to Matric Head

    * ``quantity = waterContent``

    The input data is interpreted as water content,
112 113
    :math:`f = \theta_w \, [\text{-}]`, and transformed into matric head via
    the :doc:`parameterization <parameter-file>` of the medium.
114 115 116 117 118 119 120

    Values greater than the porosity :math:`\phi` and less than the residual
    water content :math:`\theta_r` are automatically clamped to fit the allowed
    range. Additionally, any input value :math:`f(x_0)` at some position
    :math:`x_0` on the grid will result in a saturation greater zero,
    :math:`\Theta (x_0) > 0`, to avoid divergence of the matric head towards
    negative infinity.
121

122
Transport
123
^^^^^^^^^
124
Initial condition tranformations for the Transport solver.
125

126
.. object:: No Transformation
127

128
    * ``quantity = soluteConcentration``
129

130
    The input data is directly interpreted as solute concentration,
131
<<<<<<< HEAD
132
    :math:`f = c_w [\text{kg}/\text{m}^3]`.
133
=======
134 135
    :math:`f = c_w [\mathrm{kg}/\mathrm{m}^d]`, where :math:`d` indicates the
    spatial dimensions of the grid.
136
>>>>>>> master
137

138
.. _H5: https://www.h5py.org/
139
.. _muparser: http://beltoforion.de/article.php?a=muparser&p=features