Chapter 6. Creating a New Python Driver for Dakota

Note:  The script template presented in this chapter assumes Python 2.X is installed on your system.  The latest version of Python 2 is available for download here.

So far, in Chapters 2-5, the Dakota input file we’ve used for GUI examples has been rosen_multidim.in.  This input file uses a direct interface to the Rosenbrock test problem:

DakotaGuiManual_68_Chapter6_0.png

The “direct” keyword indicates that we’re using an example problem included with the Dakota executable.  However, in most real-world cases, you will want to instead use a “system” or “fork” analysis driver to hook Dakota up to an external simulation model.

Dakota works with external simulation models as demonstrated in the following flowchart:

DakotaGuiManual_68_Chapter6_1.png

On each iteration of a Dakota run…

  • Dakota specifies new variable values, based on your chosen model and method.
  • Dakota writes the new variable values to a parameters file.
  • The interface driver is called with two arguments – the Dakota parameters file, and the destination results file, where data will eventually be written out.
  • The interface driver is responsible for preparing input to the simulation model (usually by populating a text-based input file).  This step is referred to as pre-processing.
  • The simulation model is executed with the pre-processed input data.
  • After the simulation model has finished running, the interface driver is responsible for extracting quantities of interest from the simulation model’s output (usually from console output, or from a log file) and preparing it for Dakota.  This step is referred to as post-processing.
  • Finally, the driver must write to Dakota’s destination result file the response values (i.e. quantities of interest) from the simulation model.
  • At this point, Dakota collects the response values and moves on to the next iteration.

The cantilever beam test problem

In this section, we will use the cantilever beam as a test problem to demonstrate how to hook Dakota up to a simulation model via an auto-generated Python script that performs all necessary pre-processing and post-processing steps.

First, you will want to download this .zip file that includes all files necessary to run the Cantilever beam test problem.

The zip file contains three files:

  • cantilever:  The simulation model of the cantilever beam we will be running.  In reality, this is a Python script, but you can think of it as a black box that takes a single input file and returns output on the console.
  • cantilever.i:  The input file for the cantilever simulation model.  The simulation model’s input file has a special format that is foreign to Dakota.
  • dakota_cantilever_center.in:  The Dakota study that we will run.  This study performs a centered parameter study on the cantilever beam.

Import these files into a new Dakota project (see Chapter 3 for information on how to import files into the Dakota GUI).

For this tutorial, we will place the three files in the following project directories:

  • simulators/cantilever
  • simulators/cantilever.i
  • studies/dakota_cantilever_center.in

Your project should look something like the following:

DakotaGuiManual_68_Chapter6_20.PNG

The Python Dakota-to-Simulation Model Interface Wizard

Open the “Python Dakota-to-Simulation Model Interface” wizard by going to File > New > Other… and selecting it from the Dakota group:

DakotaGuiManual_68_Chapter6_2.png

Click Next.

DakotaGuiManual_68_Chapter6_3.png

Page 1 (Welcome):  This welcome page provides information about using this wizard.  Click Next.

DakotaGuiManual_68_Chapter6_4.png

Page 2 (Python File Creation):  Select the project location and name of your new Python driver script.  For this example, we will place the driver script in a “drivers” subfolder of our project and name it “MyNewDriver.py.”  Click Next.

DakotaGuiManual_68_Chapter6_5.png

Page 3 (Dakota and Simulation Model File Select):

For the first field, select the Dakota study we’ve chosen (“dakota_cantilever_center.in”).

For the second field, select the simulation model we’ve chosen (“cantilever”).

DakotaGuiManual_68_Chapter6_6.png

Page 4 (Map Dakota Variable to Simulation Model Input):

This page of the wizard covers the pre-processing step.  We will provide an example input file to our simulation model and tell the wizard which segments of text to replace at runtime.  First, provide the “cantilever.i” field in the Template File field.

DakotaGuiManual_68_Chapter6_7.png

Note that this wizard auto-populates the table with variables found in your chosen Dakota input file.  You may add or remove variables from this list if you wish (though be aware that new, unrecognized variables will be ignored at runtime).

To add pre-processor information, select a variable from the list and then select “Edit Pre-processor.”  We will select the first variable “w.”

DakotaGuiManual_68_Chapter6_8.png

In this new dialog, highlight the portion of text you want to replace at runtime with the latest value for the variable “w.”

DakotaGuiManual_68_Chapter6_9.png

Select OK.

DakotaGuiManual_68_Chapter6_10.png

Repeat this process for all variables in the list.  Variables you’re not interested in can be left blank, or removed from the list of pre-processors altogether.

DakotaGuiManual_68_Chapter6_11.png

When you’re ready, select Next.

DakotaGuiManual_68_Chapter6_12.png

Page 5 (Map Simulation Model Output to Dakota Responses):  This page of the wizard is concerned with quantity of interest extraction.  You can currently extract quantities of interest (or QOIs) from two places:

  • The standard output stream (i.e. console text) of your simulation model.
  • A single destination file on your system (i.e. a log file)

Our cantilever beam simulation model writes to the standard output stream, so we’ll leave the first radio button selected.

You may opt to provide an example template file to aid in QOI extraction, but this is an optional step.

Again, the table is pre-populated with response labels extracted from the Dakota input file.  Again, you may add or remove responses as you wish (but new, unrecognized responses will be ignored by Dakota).

To get started, click on the first item in the table and select “Edit QOI Extractor.”  We will use the response “mass” for this example:

DakotaGuiManual_68_Chapter6_13.png

Generally speaking, while output from a simulation model can vary (i.e. a log file from a given execution can be shorter or longer than the previous execution), QOIs will occur in the same place with relation to labels (or “key text”) that describe those quantities.  For instance, you might expect the following text in your output:

MASS = 0.001

To think about this dialog correctly, ask yourself how you would instruct another person to find this quantity of interest in a stream of output.  In extremely verbose terms, you might say to that person “First, locate the word MASS in the output, and then get the value that appears two fields after the word MASS.”

We can convey the same sort of expression to the Dakota GUI using this dialog.  In the case of the cantilever example problem shown so far in these screenshots, the quantity of interest is one field that appears two lines after the word MASS (you can observe this for yourself if you run the cantilever beam simulation model).  So your sentence would be “Get 1 field that is 2 lines after the key text MASS.”  Thus, you would select “1”, “field(s)”, “2”, “line(s)”, and “after” in the appropriate controls, and set the key text to “MASS.”

DakotaGuiManual_68_Chapter6_14.png

Select OK.  Then, perform this same process for the other responses.  “stress” and “displacement” will have similar QOI extraction expressions:

DakotaGuiManual_68_Chapter6_15.png

Click Next.

DakotaGuiManual_68_Chapter6_16.png

Page 6 (Execution):  On this last page of the wizard, we specify two very important things:

  • Command Line Syntax:  This field should contain a representative example of what will get run on the command line to start your simulation model.  It is not what exactly what will get run on the command line.  The Python driver script will be creating new simulation model input files for each iteration of Dakota, and thus will be providing new filenames for each of those new simulation model input files.  This is especially important to observe if you plan on running Dakota in a multithreaded (i.e. evaluation_concurrency > 1) mode.  The Python script we’re about to generate does ensure non-colliding filenames, so we don't need to worry about that.
  • Replacement Text:  This is the segment of text that you provided in your Command Line Syntax that will get replaced with the latest and greatest simulation model input file that you want to give to your simulation model.

The wizard tries to be smart and provide a recommendation in the Command Line Syntax field, but you will want to replace this text to suit your use case.  For our example, we will put “python C:/<Absolute path>/dakota_gui_workspace/Cantilever/simulators/cantilever replace_me” in the Command Line Syntax field.  This is because:

  • “python” - As mentioned earlier, our cantilever beam simulation model is actually a Python script with the .py extension removed.  For your simulation model, the syntax to launch it may be different.
  • “C:/<Absolute path>/dakota_gui_workspace/Cantilever/simulators/cantilever” – We provide Python with the absolute path to our simulation model script, rather than a relative path, for extra safety.
    • If the cantilever simulation model is known to reside in the same directory as the Python driver script, providing absolute path is not necessary.
  • “replace_me” – this is the segment of text that will get replaced using the “Replace” field below.

When you’re ready to finish, your wizard page should look like this.

DakotaGuiManual_68_Chapter6_17.png

Note:  If your Dakota input file already has an interface block specified, you can check the box at the bottom of this page to auto-substitute your new driver script into the interface block.

Finally, click Finish.  If all went well, your new Python driver script should appear as a new file in your Dakota GUI project.

Congratulations!  You’ve created a driver between Dakota and a simulation model without writing a single line of code!

DakotaGuiManual_68_Chapter6_18.png

Final Steps

Before you run this study, you will need to create a new run configuration for your Dakota input file (see Chapter 5 for information on run configurations).

  • Specify Dakota’s run directory wherever you wish.
  • Specify the Python run directory to be in the same directory where you placed your driver script.

Note:  If you’re running on Windows, you may need to change the “fork” keyword to “system” in your Dakota input file.

Run it, and you should collect data from Dakota!

DakotaGuiManual_68_Chapter6_19.png

Manual Modifications to the Python Driver Script

Because our generated driver is simply a Python script, if you know the Python language, you may wish to crack it open and modify the logic to better suit your specific use case.  For example, if your simulation model doesn’t just write out information to a single location, but to multiple locations, you may want to extract QOIs from multiple different files.

The main logic of the Python driver script begins towards the bottom of the script file, below the comment line “#Main logic”.