.. _responses-calibration_terms-field_calibration_terms:

"""""""""""""""""""""""
field_calibration_terms
"""""""""""""""""""""""


Number of field calibration terms


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

   responses-calibration_terms-field_calibration_terms-lengths
   responses-calibration_terms-field_calibration_terms-num_coordinates_per_field
   responses-calibration_terms-field_calibration_terms-read_field_coordinates


**Specification**

- *Alias:* None

- *Arguments:* INTEGER


**Child Keywords:**

+-------------------------+--------------------+-------------------------------+---------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword                | Dakota Keyword Description                  |
|                         | Group              |                               |                                             |
+=========================+====================+===============================+=============================================+
| Required                                     | `lengths`__                   | Lengths of field responses                  |
+----------------------------------------------+-------------------------------+---------------------------------------------+
| Optional                                     | `num_coordinates_per_field`__ | Number of independent coordinates for field |
|                                              |                               | responses                                   |
+----------------------------------------------+-------------------------------+---------------------------------------------+
| Optional                                     | `read_field_coordinates`__    | Add context to data: flag to indicate that  |
|                                              |                               | field coordinates should be read            |
+----------------------------------------------+-------------------------------+---------------------------------------------+

.. __: responses-calibration_terms-field_calibration_terms-lengths.html
__ responses-calibration_terms-field_calibration_terms-num_coordinates_per_field.html
__ responses-calibration_terms-field_calibration_terms-read_field_coordinates.html



**Description**


This keyword describes the number of field calibration terms.
A set of field calibration terms is a set of related response values collected over a range of
independent coordinate values which may or may not be specified by the user.
For example, voltage over time would be a field function, where voltage is
the ``field_objective`` and time is the independent coordinate.
Similarly, temperature over time and space would be a field response, where the
independent coordinates would be both time and spatial coordinates such as (x,y) or (x,y,z), depending on the application.
The main difference between scalar calibration terms and field calibration terms is that for field data, we
plan to implement methods that take advantage of the correlation or relationship between the field values.
For example, with calibration, if we want to calibrate parameters that result in a good
model fit to a time-temperature curve, we may have to do some interpolation between the experimental
data and the simulation data.  That capability requires knowledge of the independent coordinates.

Note that if there is one ``field_calibration_terms``, and it has length 100 (meaning 100 values), then
the user's simulation code must return 100 values.
Also, if there are both scalar and field calibration, the user should specify
the number of scalar terms as ``scalar_calibration_terms``.  If there are only field calibration terms,
it still is necessary to specify both ``field_calibration_terms`` = NN and ``calibration_terms`` = NN,
where NN is the number of field calibration terms.

Calibration terms are responses that are used with calibration
methods in Dakota, such as least squares optimizers.  Currently, each scalar term is added
to the total sum-of-squares error function presented to the optimizer. However,
each individual field value is added as well.   For example,
if you have one field calibration term with length 100 (e.g. a time-temperature trace
with 100 time points and 100 temperature points), the 100 temperature values
will be added to create the overall sum-of-squares error function used in
calibration.  We have an initial capability to interpolate the field data
from the user's simulation to the experimental data.  For example, if the user
has thermocouple readings at 20 time points, it will be an experimental field response
with 20 time points and 20 temperature values.  Dakota takes the 100 simulation time-temperature
values (from the example above) and interpolates those to the 20 experimental points, to create
20 residual terms (simulation minus experimental data points) that will be used in calibration.