Dakota Reference Manual  Version 6.16
Explore and Predict with Confidence
 All Pages

Supply field or mixed field/scalar calibration data


Alias: none

Argument(s): none

Child Keywords:

Required/Optional Description of Group Dakota Keyword Dakota Keyword Description
Optional data_directory

Specify a directory containing the calibration field data files used with the mixed case specification

Optional num_experiments Add context to data: number of different experiments
Optional num_config_variables

Add context to data: number of configuration variables.

Optional experiment_variance_type

Add context to data: specify the type of experimental error

Optional scalar_data_file

Specify a scalar data file to complement field data files (mixed case)

Optional interpolate

Flag to indicate interpolation of simulation values.


calibration_data specifies a keyword block that indicates that Dakota should read in experimental data for calibration. This block is primarily to support the reading of field calibration data. For simpler, scalar-only response cases, see calibration_data_file. The user will typically specify the number of experiments, num_experiments. If this is not specified, it is assumed there is only one experiment.

Up to four types of data may be read. They are read from a collection of files, one per response descriptor, per experiment. In this discussion, DESC refers to the response descriptor and NUM to the experiment number.

  1. Values: The scalar or field-valued response function values, e.g., temperature values, voltage levels. These are read from files named DESC.NUM.dat (one per response descriptor, per experiment), e.g, volts.1.dat, volts.2.dat. Scalar files will contain a single value, while field files will each contain a column of field reponse values. Without interpolate enabled, the lengths of these files must match those specified using the responses-calibration_terms-field_calibration_terms-lengths keyword.
  2. Coordinates: Field coordinates specify independent variables (e.g., spatial or temporal coordinates) upon which the field depends. For example, the voltage might be a function of time, so time is the field coordinate. These are read from files named DESC.NUM.coords, each containing num_coordinates_per_field columns. The number of rows must be the same as in the values files described in the previous bullet.
  3. Variances: If experiment_variance_type is specified, variance values are read from files DESC.NUM.sigma. Note that a single experiment_variance_type may be specified, or a unique experiment_variance_type per response descriptor (per scalar or field). If the experiment_variance_type is:
    • 'scalar': a single variance value will be read from the file.
    • 'diagonal' (field responses only): a column vector of variance values (length equal to the number of experimental data points) will be read from the file. The values are the variances of each field value for this descriptor.
    • 'matrix' (field responses only): a matrix of covariance values (square with size the number of experimental values) will be read from the file. The matrix is a full covariance matrix for the components of this field response. While covariance among entries in a field response may be specified, covariance among experiments is not permitted.
  4. Configuration variables: specify the conditions corresponding to different experiments. When responses-calibration_terms-calibration_data-num_config_variables is specified, the configuration variable values for each experiment should be placed in a file named experiment.NUM.config, where the number of items in that config file are the num_config_variables. These variables are used as auxilliary state variables for the simulation (for example) and are not calibrated.

    Attention: In versions of Dakota prior to 6.14, string-valued configuration variables were specified in data files with 0-based indices into the admissible values. As of Dakota 6.14, strings must be specified by value. For example a string-valued configuration variable for an experimental condition might appear in the file as low_pressure vs. high_pressure.

Aggregating scalar data: The above description is primarily relevant for field data (with files for field values, field coordinates, field variances). If the user also has scalar experimental data, it may be entered as described above, i.e., one file named DESC.NUM.dat per scalar response. However, an alternative is to provde the data for all scalar responses in aggregate in the simpler scalar_data_file format, with the number of rows of that file equal to the number of experiments. The scalar data file may be used in combination with the the separate field files described above.

Interpolation: One important feature of field data is the capability to interpolate between points in the field. For example, we may have simulation data at a set of responses $ y $ at time points $ t $: ( $ t_{s1}, y_{s1} $), ( $ t_{s2}, y_{s2} $), etc. In this example, $ t $ is the independent coordinate for the simulation, and the simulation time and response points are denoted with subscripts $ s1, s2, s3, $. If the user has experimental data that is taken at different time points: ( $ t_{e1}, y_{e1} $), ( $ t_{e2}, y_{e2} $), ..., it is necessary to interpolate the simulation data to provide estimates of the simulation response at the experimental time points to construct the residual terms (model - experiment) at the experimental time points. Dakota can perform 1-D interpolation. The user must specify the keyword interpolate, and also provide the field coordinates as well as field values for the experiment data.

If the interpolate keyword is not specified, Dakota will assume that the simulation field data and the experiment field data is taken at the same set of independent coordinate values and simply construct the difference between these field terms to create the set of residuals for the sum-of-squares calculation. When interpolate is specified, the simulation coordinates are assumed fixed and the same for each simulation. These simulation coordinates are provided in DESC.coords. However, the experiment coordinates for each experiment can be different, and are provided in the files numbered by experiment with the file names given by DESC.NUM.coords, as indicated above.


Consider this field example with three field-valued responses (volts as a function of 7 time points, amps as a function of 3 time points, and power as a function of 5 time points). The experiments each have one coordinate (time) per field. The experiments were conducted given values of two configuration variables. There are four experiments (note that there often is only one experiment).

  descriptors = 'volts' 'amps' 'power'
  calibration_terms = 3

    #define field terms
    field_calibration_terms = 3
      lengths = 7 3 5
      num_coordinates_per_field = 1 1 1
    # specify the data
      num_experiments = 4
      num_config_variables = 2
      experiment_variance_type 'diagonal' 'scalar' 'matrix' 

The field data will be read from separate files:

  1. Values: 7 values for voltage as a function of time will be read from each of volts.1.dat ... volts.4.dat, while the 3 values of amperage come from amps.1.dat, ..., amps.4.dat and the 5 values of power will come from power.1.dat, ..., power.4.dat.

  2. Coordinates: The corresponding time values will be read from a single column vector in each of the files volts.*.coords, amps.*.coords, and power.*.coords.
  3. Variances: Will be read per-experiment (no covariance among experiments is permitted). The variance information is depicted graphically in experiment_variance_type
    • Volts specifies 'diagonal' covariance, so a column vector of length 7 with the diagonal variances will be read from each of volts.1.sigma, ..., volts.4.sigma.
    • Amps specifies 'scalar' covariance, so a single variance value will read from each of amps.1.sigma, ..., amps.4.sigma.
    • Power specifies 'matrix' covariance, so a square 5 x 5 covariance matrix will be read from each of power.1.sigma, ..., power.4.sigma.
  4. Configuration variables: Will be read from a set of files named experiment.1.config, ..., experiment.4.config.