.. _model-random_field:

""""""""""""
random_field
""""""""""""


Experimental capability to generate a random field representation.
from data, from simulation
runs, or from a covariance matrix.  The representation may then be sampled
for use as a random field input to another simulation.  THIS IS AN EXPERIMENTAL CAPABILITY.


.. toctree::
   :hidden:
   :maxdepth: 1

   model-random_field-build_source
   model-random_field-expansion_form
   model-random_field-expansion_bases
   model-random_field-truncation_tolerance
   model-random_field-propagation_model_pointer


**Specification**

- *Alias:* None

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+-------------------------------+---------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword                | Dakota Keyword Description                  |
|                         | Group              |                               |                                             |
+=========================+====================+===============================+=============================================+
| Optional                                     | `build_source`__              | Specify how the random field will be built: |
|                                              |                               | from a data file, from simulation runs, or  |
|                                              |                               | from a covariance matrix. THIS IS AN        |
|                                              |                               | EXPERIMENTAL CAPABILITY.                    |
+----------------------------------------------+-------------------------------+---------------------------------------------+
| Optional                                     | `expansion_form`__            | Specify the form of the expansion to be     |
|                                              |                               | used in the random field representation.    |
|                                              |                               | THIS IS AN EXPERIMENTAL CAPABILITY.         |
+----------------------------------------------+-------------------------------+---------------------------------------------+
| Optional                                     | `expansion_bases`__           | Specify the number of basis functions to be |
|                                              |                               | used in the random field representation.    |
|                                              |                               | THIS IS AN EXPERIMENTAL CAPABILITY.         |
+----------------------------------------------+-------------------------------+---------------------------------------------+
| Optional                                     | `truncation_tolerance`__      | Specify a percent of the response variance  |
|                                              |                               | that should be captured with the random     |
|                                              |                               | field representation. THIS IS AN            |
|                                              |                               | EXPERIMENTAL CAPABILITY.                    |
+----------------------------------------------+-------------------------------+---------------------------------------------+
| Required                                     | `propagation_model_pointer`__ | Pointer to the model that will accept       |
|                                              |                               | realizations of the random field and use    |
|                                              |                               | them for subsequent analysis. Typcially,    |
|                                              |                               | this model will take the random field as    |
|                                              |                               | inputs, e.g. a random field defining a      |
|                                              |                               | pressure boundary or temperature boundary   |
|                                              |                               | condition over a structure. THIS IS AN      |
|                                              |                               | EXPERIMENTAL CAPABILITY.                    |
+----------------------------------------------+-------------------------------+---------------------------------------------+

.. __: model-random_field-build_source.html
__ model-random_field-expansion_form.html
__ model-random_field-expansion_bases.html
__ model-random_field-truncation_tolerance.html
__ model-random_field-propagation_model_pointer.html



**Description**


Capability to generate a random field representation from data, from simulation
runs, or from a covariance matrix.  The random field may then be sampled
for use as a random field input to another simulation.  THIS IS AN EXPERIMENTAL CAPABILITY UNDER ACTIVE DEVELOPMENT.

*Default Behavior*
There are three main sections of the ``random_field`` model.
The first section tells Dakota what data to use to build the random field.
This is specified with ``build_source``.  The source of data to build the
random field may be a file with data (where the N rows of data correspond to
N samples of the random field and the M columns correspond to field values),
or it may be a simulation that generates field data, or it may be specified
given a mesh and a covariance matrix governing how the field varies over the mesh.
In the case of using a simulation to generate field data, the simulation is
defined with ``dace_method_pointer``.  In the case of using a mesh and a
covariance, the form of the covariance is defined with ``analytic_covariance``.

The next section of the random fiel model specifies the form of the expansion,
``expansion_form``.  This can be either a Karhunen-Loeve expansion or a
Principal components analysis.  These are very similar:  both involve the eigenvalues
of the covariance matrix of the field data.  The only difference is in the treatment
of the estimation of the coefficients of the eigenvector basis functions.  In the
PCA case, we have developed an approach which makes the coefficients explicit
functions of the uncertain variables used to generate the random field.
The specification of the random field can also include the number of bases
to retain or a truncation tolerance, which defines the percent variance
that the expansion should capture.

The final section of the random field model allows the user to specify
a pointer to a model over which the random field will be propagated,
meaning the model which will be driven with the random field input.
This part of the specification is optional:  one can build a random field but
not use it in a downstream model.



**Examples**


As stated above, this is an emerging capability.
The syntax currently looks like the following:

.. code-block::

    random_field
       build_source
         rf_data_file | dace_method_pointer | analytic_covariance
       expansion_form
         karhunen_loeve | principal_components
         expansion_bases
         truncation_tolerance
       propagation_model_pointer