JSON Format Input Files

A Dakota input file can be written in JSON format. A JSON input file describes the same study as a freeform input file: the same six blocks and the same keywords, written as nested JSON objects. Because JSON is a standard format, scripts and other tools can easily generate, read and check Dakota studies written in it. Both formats are fully supported. For a side-by-side introduction to the two formats, see Two formats, one structure.

To run a JSON input file, use the -json command-line option:

dakota -json study.json

The JSON schema (that is, the specification of the allowed structure and content of JSON input files) is defined by a set of Pydantic models, which are documented in Pydantic Model Reference. You don’t need to understand the models to use the JSON format. Most users will find this page and Dakota’s Keyword Reference more helpful when writing JSON input files.

Example JSON Input

The following example illustrates the main features of Dakota’s JSON format.

 1{
 2  "environment": {
 3    "tabular_data": {}
 4  },
 5  "method": [
 6    {
 7      "optpp_g_newton": {
 8        "convergence_tolerance": 0.0001,
 9        "max_iterations": 100
10      }
11    }
12  ],
13  "model": [
14    {
15      "single": {}
16    }
17  ],
18  "interface": [
19    {
20      "analysis_drivers": {
21        "drivers": [
22          "rosenbrock"
23        ],
24        "interface_type": {
25          "direct": {}
26        }
27      }
28    }
29  ],
30  "responses": [
31    {
32      "gradient_type": {
33        "analytic_gradients": true
34      },
35      "hessian_type": {
36        "no_hessians": true
37      },
38      "response_type": {
39        "calibration_terms": {
40          "count": 2
41        }
42      }
43    }
44  ],
45  "variables": [
46    {
47      "continuous_design": {
48        "count": 2,
49        "descriptors": [
50          "x1",
51          "x2"
52        ],
53        "initial_point": [
54          -1.2,
55          1.0
56        ],
57        "lower_bounds": [
58          -2.0,
59          -2.0
60        ],
61        "upper_bounds": [
62          2.0,
63          2.0
64        ]
65      }
66    }
67  ]
68}

Top-level Organization

A JSON format input file must contain a single object. As specified in the DakotaStudy model, this object has:

  • an optional environment key (line 2), whose value is another object that contains configuration information for the environment block.

  • a required method key (line 5), whose value is an array of length 1 or more of method configuration objects.

  • an optional model key (line 13), whose value is an array of length 0 or more of model configuration objects.

  • required interface, responses, and variables keys (lines 18, 30, 45), whose values are arrays of length 1 or more of configuration objects for those blocks.

The structure of the overall study is specified by the DakotaStudy model.

Leaf Keywords

Keywords that have no children (“leaf” keywords) receive a constant true argument. In the example input in the preceding section, the keys analytic_gradients (line 33) and no_hessians (line 36) are instances of this.

Empty Objects

Empty objects are used when a keyword can have optional child keywords, none of which happen to be present in a particular study. The tabular_data (line 3) and single (line 15) keys are examples.

Group keys

Where a study must choose one of several mutually exclusive keywords, the JSON format wraps the choice in an intermediate object, called a group key or anchor, that names what is being chosen. Group keys make the structure unambiguous. In the example, gradient_type (line 32) and hessian_type (line 35) are group keys: each holds the one gradient or Hessian option the study uses. The freeform format has no group keys; there, the chosen keyword appears directly.

In the Keyword Reference, JSON Group Keys are documented in each keyword’s child keyword table.

Argument keys

Some keywords take a value and also have child keywords. A JSON object can’t have both a value and children, so the keyword’s own value goes in a separate child field, called an argument key. For example, count (line 48) holds the number of continuous design variables. In the freeform format, the same value is written directly after the keyword (continuous_design = 2).

In the Keyword Reference, Argument Keys appear in the Specification section of each keyword’s documentation.

Nonfinite numbers

Nonfinite numbers such as inf and nan are not natively supported by JSON. They must be provided as quoted strings (“inf”, “nan”) in Dakota input.

Converting Freeform Input Files

If you already have freeform input files, Dakota’s dakota_parser tool can convert them to JSON.

Using dakota_parser

  1. Begin with a working freeform input file.

  2. Run dakota_parser, located in the bin folder of the Dakota install, to generate the corresponding JSON: dakota_parser <freeform dakota input> --json

  3. Use the result as a starting point, modifying it as needed. The output includes every setting, with default values filled in for the ones your freeform file left out. You can delete the defaults you don’t need, to keep the file short.

  4. Refer to the Keyword Reference and Pydantic documentation to understand and refine specific fields.

Freeform features that JSON doesn’t support

Some of the convenience features supported in freeform input files do not work in JSON. These include keyword aliases (e.g. using nond_sampling in place of sampling), abbreviations (e.g. using analysis_driver when the full keyword is analysis_drivers), shortcut notations such as N*Value and L:S:U sequences, and input file template pre-processing.