Tutorial: Your First Dakota Study

In this tutorial you run three different Dakota studies: with a function built into Dakota (a direct interface), with the same function run as a black-box simulation through an analysis driver, and with the same analysis driver but changing the method.

Prerequisites: Dakota installed, with its bin folder on your PATH (see Installation and Setting Your Environment). For Part B you also need Python 3, with Dakota’s Python folder on your PYTHONPATH.

The example throughout is Rosenbrock’s function of two variables, x1 and x2. If you haven’t been introduced to it yet, see The example: Rosenbrock.

Every input file below is shown in both of Dakota’s input formats. Choose the JSON or Freeform tab, and the whole page follows your choice.

Part A: Run a built-in example

  1. Check that Dakota runs. This command prints Dakota’s version:

    dakota -v
    
  2. Create an empty folder for this part, and open a terminal in it.

  3. Create the input file:

    Save this as rosen_multidim.json:

    {
      "environment": {
        "tabular_data": {
          "tabular_data_file": "rosen_multidim.dat"
        }
      },
      "method": [
        {
          "multidim_parameter_study": {
            "partitions": [8, 8]
          }
        }
      ],
      "model": [
        {
          "single": {}
        }
      ],
      "variables": [
        {
          "continuous_design": {
            "count": 2,
            "descriptors": ["x1", "x2"],
            "lower_bounds": [-2.0, -2.0],
            "upper_bounds": [2.0, 2.0]
          }
        }
      ],
      "interface": [
        {
          "analysis_drivers": {
            "drivers": ["rosenbrock"],
            "interface_type": {
              "direct": {}
            }
          }
        }
      ],
      "responses": [
        {
          "gradient_type": {
            "no_gradients": true
          },
          "hessian_type": {
            "no_hessians": true
          },
          "response_type": {
            "response_functions": {
              "count": 1
            }
          }
        }
      ]
    }
    

    Copy rosen_multidim.in from the share/dakota/examples/users/ folder of your Dakota installation, or save this as rosen_multidim.in:

    # Dakota Input File: rosen_multidim.in
    # Usage:
    #   dakota -i rosen_multidim.in -o rosen_multidim.out > rosen_multidim.stdout
    
    environment
      tabular_data
        tabular_data_file = 'rosen_multidim.dat'
    
    method
      multidim_parameter_study
        partitions = 8 8
    
    model
      single
    
    variables
      continuous_design = 2
        lower_bounds     -2.0     -2.0
        upper_bounds      2.0      2.0
        descriptors       'x1'     "x2"
    
    interface
      analysis_drivers = 'rosenbrock'
        direct
    
    responses
      response_functions = 1
      no_gradients
      no_hessians
    

    It describes an 81-point grid study of Rosenbrock’s function, using the copy of the function built into Dakota. Anatomy of a Dakota Study explains each block.

  4. Run Dakota:

    dakota -json rosen_multidim.json -o rosen_multidim.out > rosen_multidim.stdout
    
    dakota -i rosen_multidim.in -o rosen_multidim.out > rosen_multidim.stdout
    

What happened

Dakota ran Rosenbrock’s function 81 times and wrote four files:

  • rosen_multidim.stdout: Dakota’s progress messages, which would otherwise appear on the screen.

  • rosen_multidim.out: details of each evaluation, and a summary at the end.

  • rosen_multidim.dat: the tabular data file, with one row per evaluation. Its first rows are:

    %eval_id interface             x1             x2  response_fn_1
    1            NO_ID             -2             -2           3609
    2            NO_ID           -1.5             -2         1812.5
    3            NO_ID             -1             -2            904
    
  • dakota.rst: a binary restart file. If a study is interrupted, Dakota can use it to continue without repeating finished evaluations.

The 81 points form a 9 × 9 grid over the range of x1 and x2:

An evenly spaced 9 by 9 grid of points over x1 and x2 from -2 to 2, drawn over a contour plot of Rosenbrock's function.

Fig. 6 The points evaluated by the grid study.

You can open the tabular data file in a spreadsheet or plotting tool to explore the results. Dakota Output describes all of Dakota’s output files.

Part B: The same problem as a black box

Now run the same study, but Dakota treats Rosenbrock’s function as a black box: a separate program that reads an input file and writes an output file, like an engineering simulation code. Dakota connects to it through an analysis driver. Connecting Your Code: The Analysis Driver explains the ideas behind each step.

  1. Create a new, empty folder for this part, open a terminal in it, and copy in the black-box simulation and its input template from your Dakota installation:

    cp <install_dir>/share/dakota/examples/official/drivers/bash/templatedir/* .
    
    Copy-Item "<install_dir>\share\dakota\examples\official\drivers\bash\templatedir\*" .
    

    Replace <install_dir> with the folder where you installed Dakota. You now have two files:

    • rosenbrock_bb.py, the simulation. It reads an input deck, ros.in, and writes a log, ros.out.

    • ros.template, a copy of the input deck with {x1} and {x2} where the variable values go.

  2. Save one of these analysis drivers in the same folder, as driver.py, driver.sh or driver.ps1:

    This version uses Dakota’s dakota.interfacing Python module to read the parameters file, fill in the template, and write the results file.

    #!/usr/bin/env python3
    # Analysis driver for the black-box Rosenbrock example.
    # Dakota runs it as:  python3 driver.py params.in results.out
    
    import subprocess
    import sys
    
    import dakota.interfacing as di
    
    # Read the parameters file Dakota wrote, and set up the results file.
    params, results = di.read_parameters_file()
    
    # --------------
    # PRE-PROCESSING
    # --------------
    # Put this evaluation's x1 and x2 into the simulation's input file.
    di.dprepro(template="ros.template", parameters=params, output="ros.in")
    
    # ---------
    # EXECUTION
    # ---------
    subprocess.run([sys.executable, "rosenbrock_bb.py"], check=True)
    
    # ---------------
    # POST-PROCESSING
    # ---------------
    # Find the function value in the simulation's output, and return it to
    # Dakota as the first (and only) response.
    with open("ros.out") as f:
        for line in f:
            if "Function value" in line:
                value = float(line.split("=")[1])
    
    results[0].function = value
    results.write()
    

    This version uses the dprepro command to fill in the template, and grep and awk to find the value in the output.

    #!/usr/bin/env bash
    # Analysis driver for the black-box Rosenbrock example.
    # Dakota runs it as:  driver.sh params.in results.out
    
    params=$1
    results=$2
    
    # --------------
    # PRE-PROCESSING
    # --------------
    # Put this evaluation's x1 and x2 into the simulation's input file.
    dprepro "$params" ros.template ros.in
    
    # ---------
    # EXECUTION
    # ---------
    python3 rosenbrock_bb.py
    
    # ---------------
    # POST-PROCESSING
    # ---------------
    # Find the function value in the simulation's output, and return it to
    # Dakota as the first (and only) response.
    grep 'Function value' ros.out | awk '{print $4}' > "$results"
    

    Note

    dprepro runs with the python command. If your system has only python3, use dprepro3 instead, which runs dprepro with python3.

    This version runs dprepro with Python to fill in the template, and uses Select-String to find the value in the output.

    # Analysis driver for the black-box Rosenbrock example.
    # Dakota runs it as:  powershell.exe -File driver.ps1 params.in results.out
    
    $params = $args[0]
    $results = $args[1]
    
    # --------------
    # PRE-PROCESSING
    # --------------
    # Put this evaluation's x1 and x2 into the simulation's input file.
    $dprepro = (Get-Command "dprepro").Path
    python3 $dprepro $params ros.template ros.in
    
    # ---------
    # EXECUTION
    # ---------
    python3 rosenbrock_bb.py
    
    # ---------------
    # POST-PROCESSING
    # ---------------
    # Find the function value in the simulation's output, and return it to
    # Dakota as the first (and only) response.
    $line = Select-String -Path ros.out -Pattern "Function value"
    $value = ($line.Line -split "=")[1].Trim()
    Set-Content -Path $results -Value $value -Encoding ASCII
    

    On Linux and macOS, make a Bash driver executable with chmod +x driver.sh.

  3. Test the analysis driver by hand. Save this sample parameters file as params.in. It is what Dakota writes for the first evaluation, where x1 and x2 are both -2:

                         2 variables
    -2.000000000000000e+00 x1
    -2.000000000000000e+00 x2
                         1 functions
                         1 ASV_1:response_fn_1
                         2 derivative_variables
                         1 DVV_1:x1
                         2 DVV_2:x2
                         0 analysis_components
                         1 eval_id
    

    Then run your analysis driver on it:

    python3 driver.py params.in results.out
    
    ./driver.sh params.in results.out
    
    powershell.exe -File driver.ps1 params.in results.out
    

    Look at the files the driver created:

    • ros.in: the template, with -2 filled in for both variables;

    • ros.out: the simulation’s log, including the line Function value =  3.6090000000000000e+03;

    • results.out: the value 3609, ready for Dakota.

    If something goes wrong, see Test your analysis driver before running Dakota.

  4. Create the input file. It is the same as Part A’s, except for the highlighted interface block, which now runs your analysis driver:

    Save this as rosen_blackbox.json:

    {
      "environment": {
        "tabular_data": {
          "tabular_data_file": "rosen_multidim.dat"
        }
      },
      "method": [
        {
          "multidim_parameter_study": {
            "partitions": [8, 8]
          }
        }
      ],
      "model": [
        {
          "single": {}
        }
      ],
      "variables": [
        {
          "continuous_design": {
            "count": 2,
            "descriptors": ["x1", "x2"],
            "lower_bounds": [-2.0, -2.0],
            "upper_bounds": [2.0, 2.0]
          }
        }
      ],
      "interface": [
        {
          "analysis_drivers": {
            "drivers": ["python3 driver.py"],
            "interface_type": {
              "fork": {}
            }
          }
        }
      ],
      "responses": [
        {
          "gradient_type": {
            "no_gradients": true
          },
          "hessian_type": {
            "no_hessians": true
          },
          "response_type": {
            "response_functions": {
              "count": 1
            }
          }
        }
      ]
    }
    

    Save this as rosen_blackbox.in:

    environment
      tabular_data
        tabular_data_file = 'rosen_multidim.dat'
    
    method
      multidim_parameter_study
        partitions = 8 8
    
    model
      single
    
    variables
      continuous_design = 2
        lower_bounds     -2.0     -2.0
        upper_bounds      2.0      2.0
        descriptors       'x1'     'x2'
    
    interface
      analysis_drivers = 'python3 driver.py'
        fork
    
    responses
      response_functions = 1
      no_gradients
      no_hessians
    

    If you saved the Bash or PowerShell driver, change the analysis_drivers value to 'driver.sh' or 'powershell.exe -File driver.ps1'.

  5. Run Dakota:

    dakota -json rosen_blackbox.json -o rosen_blackbox.out > rosen_blackbox.stdout
    
    dakota -i rosen_blackbox.in -o rosen_blackbox.out > rosen_blackbox.stdout
    
  6. Compare rosen_multidim.dat in this folder with the one from Part A. The values are the same: Dakota ran the black-box simulation 81 times through your analysis driver, and got the same answers as the built-in function.

Part C: One interface, many methods

Your analysis driver works with any Dakota method. In the Part B folder, replace the method block of your input file with this one, and leave everything else unchanged:

{
  "method": [
    {
      "sampling": {
        "samples": 20,
        "seed": 52983
      }
    }
  ]
}
method
  sampling
    samples = 20
    seed = 52983

Run Dakota again with the same command as in Part B. Instead of a grid, sampling runs 20 points spread through the range of x1 and x2 by Latin hypercube sampling. The new rosen_multidim.dat has 20 rows. Fixing the seed makes the points the same each time you run.

You changed the method without touching your code or your analysis driver. That is the main idea behind Dakota: build one interface, then use many methods. To see which methods Dakota offers, and which questions each kind of study answers, see Study Types.

Next steps

Video Resources

Watch Screencast 1.1: Running a Simple Example in Dakota

Next: Study Types