Table of Contents

1. Dakota Project Wizard
2. Dakota Study Wizard
3. Dakota Wrapper Workflow Wizard
4. Script-Based Dakota Driver Wizard
5. Workflow-Based Dakota Driver Wizard

Dakota Project Wizard

You can create a new Dakota project using the Dakota Project wizard.

Go to File > New > Project, then select Dakota > Dakota Project from the available options:

The New Dakota Project wizard only has one page:

Put the name of your new project in the "Project name" field and click Finish. At this time, you should see your new project appear in the Project Explorer view.

Dakota Study Wizard

The Dakota Study wizard allows you to wrap an existing, parameterized simulation model with a Dakota study. This wizard is ideal for new Dakota users who are not familiar with Dakota input file syntax, but would like to have a new Dakota study up and running with minimal effort.

That being said, this wizard is usually not the first step for a new Dakota study. There are two prerequisites to using this wizard. You will need:

• A parameterized simulation model that can be recognized as having variables and responses. We recommend either using a BMF file or a Next-Gen Workflow file that wraps an external simulation model.
• An interface for Dakota to communicate with the simulation model. We recommend either using a Python driver script or a Next-Gen Workflow file that wraps an external simulation model.

You can open this wizard via "File > New > Dakota Study".

Page 1 (Dakota Study File Creation)

On the first page, simply choose a file name and location for your new Dakota study.

Page 2 (Import Variables and Responses)

Select the file that will provide variable and response information to the wizard. This file is the first of the two prerequisites mentioned in the introduction.

Pro Tip: Some file types (such as IWF workflow files) are "one-stop shops" for the Dakota Study wizard. They can provide variable and response information on this "Import Variables and Responses" page of the wizard, but can also provide information as to how Dakota should interface with the IWF file (the last page of the wizard).

The Preview Button

From the "Method Settings" page onward, you’ll notice a "Preview" button in the bottom-left corner of the wizard. Hit this button at any moment to pop up another dialog that shows a preview of the Dakota study, so that you can observe how your Dakota study is coming along as you go through this wizard.

Page 3 (Method Settings)

Because Dakota is home to a large number of methods for different types of studies, providing a comprehensive list of methods on this page would not be helpful. Instead, this page of the wizard guides you to a method recommendation based on how you answer a series of questions. For example, if you choose "Basic Parameter Sweep" in the first dropdown, you will be presented with a subsequent dropdown:

In response to your choice of "Basic Parameter Sweep", the wizard recommends three related methods – centered_parameter_study, vector_parameter_study, and multidim_parameter_study – each of which takes a slightly different approach to doing a parameter sweep of your problem.

At this juncture, you can hit the “?” button to open the Dakota reference manual and find out more about your chosen method.

Page 4 (Variable Settings)

The variables page allows you to configure the variables of your Dakota study. There is a lot packed onto this page, so let’s go through it one section at a time.

First of all, notice the table. It is auto-populated with variables from your chosen source of variables and responses.

• Selection Column By default, each imported variable is selected. Sometimes, we only want to provide Dakota with a subset that represents the variables we’re interested in. To de-select an individual variable, simply click on the green checkmark. To select it again, click on the red X.
• Lock Column The lock icon indicates that a given variable was imported from another simulation model, and thus its label cannot be changed. However, you are free to add extra Dakota variables using the "Add New Variable" button. These will not have the same lock icon, indicating that they can be re-labeled or deleted.
• Variable Column This column shows the variable name imported from the simulation model file, as well as the names of any user-defined variables. Only user-added variables have editable names.
• Category Column Clicking in a cell in this column will provide you with a dropdown containing categories for your variables. Categorizing variables is a required step for building a Dakota study. Note that this dropdown list only contains variable categories that are appropriate for the type of study you chose to perform back on the Method Settings page.

Let’s also take a look at the button bar…

From left to right…

• Add New Variable This button allows you to add your own user-defined variables to the Dakota study. This can be handy in the case where you’re building your Dakota study without a prior source of variables and responses. It's not recommended if you want your new Dakota study to adhere closely to an existing simulation model. On the other hand, if you know for a fact that your Dakota-to-simulation-model workflow can handle user-defined variables, go ahead and create them here.
• Edit Variable After a variable has been assigned to a category (for instance, continuous_design), use the Edit button to configure properties on that variable.
• Remove Variable Delete a variable from the variables page. You can only delete user-created variables; you cannot delete imported variables.
• Variable Ordering within Category Dakota variables are ordered first by variable category (sometimes referred to as "spec order"), and then by user-customized ordering within that category. This button allows you to configure the latter.
• Enable All Batch-enable all your variables.
• Disable All Batch-disable all your variables.
• Reset to Model Defaults This reverts all your work on the variables page back to the state when you first imported from your source of variables and responses. A warning dialog appears when you hit this button (in case you click on it by mistake).
• Open Dakota Reference Manual Opens the Dakota reference manual for the selected variable category (for instance, continuous_design).
• Batch-assign category Auto-assign every variable to the same category.

Variable Properties

After assigning a variable to a category (such as continuous_design), we can further assign specific properties on that variable. To do this, click on the variable in the table, then click on the Edit Variable button (the second button from the left).

A new dialog will pop up that allows you to edit each possible property for that variable category. Help buttons are provided for each property so that you can read up on what each one does.

Page 5 (Response Settings)

The response settings page is a mirror of the variable settings page, with a few key differences:

• Response Type Dakota responses have a global category of either response_functions, calibration_terms, or objective_functions.
• Gradients Use this dropdown to select a gradient setting for your study.
• Hessians Use this dropdown to select a hessian setting for your study.

Page 6 (Interface Settings)

There are just a few options on this page.

• Analysis Driver Selection Use this file selector to select the driver we created in this section. If you used the Script-Based Dakota Driver wizard, select the generated .im file. If you created a nested workflow, select the .iwf file. After selecting, hit the Preview button to see that the Dakota Study wizard has automatically figured out the correct settings for the interface block based on our analysis driver type.
• Evaluation concurrency (number of threads) Use this option to configure how multithreaded you want Dakota to be.

Dakota Wrapper Workflow Wizard

Why would you want to create a workflow that does nothing but execute a Dakota input file?

A Dakota study that was created using the New Dakota Study wizard and set up to interface with a Next-Gen Workflow IWF file as the analysis driver will have an interface block that looks something like this:

Note that the value for the analysis_drivers keyword is "SAW_DRIVER." Without going too far down into the details, "SAW_DRIVER" is a "magic string" that the Next-Gen Workflow engine recognizes and replaces at runtime with the appropriate information needed to make Dakota call into the IWF file as the analysis driver.

However, in order to perform this magic replacement, we can’t directly execute Dakota as normal. Executing "dakota -input my_cool_input_file.in" on the command line won't work for this input file. And using an Eclipse run configuration on this file won't work either. That's because "SAW_DRIVER" is meaningless until it gets substituted with the appropriate information. For this situation, we need to create a second wrapper workflow that launches Dakota for us. This is the right answer because the "dakota" node in Next-Gen Workflow knows how to substitute "SAW_DRIVER" with the right information at runtime.

You can access the Dakota Wrapper Workflow Wizard via "File > New > Other" and then "Dakota > Dakota Wrapper Workflow". You can also right-click on a Dakota input file and choose "New > Wrapper workflow for Dakota".

This wizard is extremely short. On the first page, choose a name and location for your wrapper workflow (a common convention is to call it "RunDakota.iwf")

On the second and final page of the wizard, use the file selector control to select your target Dakota input file. If you used the context menu option for launching the wizard, this field will already be populated.

Hitting Finish will generate a run-ready workflow that executes your Dakota study in concert with the first Dakota driver workflow you created earlier:

Script-Based Dakota Driver Wizard

The Script-Based Dakota Driver Wizard allows you to create an analysis driver for Dakota that is a script file. This script file will facilitate the transfer of input parameters and output responses between a Dakota study and your external simulation model.

You can use this wizard even before you've created your Dakota study - all you need is a list of supported variable labels and supported response labels that you want the driver script to handle. We recommend using the BMF file format to define this list of variables and responses if you don't yet have a Dakota study. If you do already have a Dakota study, you can simply provide the Dakota study as the source of variables and responses.

In this version of Dakota GUI, Python 3 is the only language that is supported for generated driver scripts, so you will need to have Python 3 installed to run the generated script.

Open the Script-Based Dakota Driver wizard by going to File > New > Script-Based Dakota Driver.

Page 1 (Welcome)

This welcome page provides some overview information about this wizard.

Page 2 (Python File Creation)

Select the project location and name of your new Python driver script.

Page 3 (Data Source Files Selection)

On this page, we provide our driver script with two things – information about the parameters and responses we’ll be using, and the path to our simulation model executable.

For the first file selector field ("Select variable/response source file"), click on the ellipsis button and choose your source of variables and responses. As discussed earlier, this could be a BMF file, or possibly a Dakota study file. After selecting a file, this wizard should register the number of variables and responses found in that file:

For the second file selector field (“Select a simulation model file”), you are not required to use resources imported into the Dakota GUI workspace. You can browse to anywhere on your file system to get the simulation model file. You could also simply type in the name of your simulation model executable file (for instance, if it is on your system PATH).

Page 4 (Map Variables to Simulation Model Input)

This page of the wizard covers the pre-processing step. There are two ways to pre-process a file in this wizard - you can either provide text-based pre-processing markup, or define positional pre-processors.

Text Markup (APREPRO or DPREPRO)

If you've defined APREPRO or DPREPRO as your preferred pre-processor in the global Preferences for Dakota GUI, you will see the following page:

All that is required on this page is to provide a marked-up template file using the "Template File" file selector:

After selecting a marked-up template file, the wizard will perform a check that compares detected markup in your file against the list of variable labels you provided earlier. If everything is good, all variables will have green checkmarks next to them in the "Markup Summary" group. If a variable label could not be matched to any markup in the file, then a red X will appear next to that variable:

On the other hand, partial matches that the wizard is suspicious of will receive a yellow caution sign. These might still be replaceable at runtime, depending on whether you are using APREPRO or DPREPRO, but it's not guaranteed to work.

If you need help marking up a template input file in the first place, we recommend exiting the wizard and using the Markup File tool.

Positional Pre-processing

If you've defined Positional Pre-processing as your preferred pre-processor in the global Preferences for Dakota GUI, you will see the following page:

The "Template File" file selector allows you to provide an example input file that will be pre-processed at runtime.

Note that this wizard auto-populates the table with variable labels. These variable labels came from the variable/response source file that you provided earlier. You may add or remove variables from this list if you wish (adding variables is not really recommended, but not disallowed either).

To add pre-processor information, select a variable from the list and then select "Edit Pre-processor."

In this new dialog, highlight the portion of text you want to replace at runtime. In the example screenshot below, the text "500" will be replaced by whatever value that Dakota provides for the input variable "horizontal".

When you're done, select OK. Here is an example of what your wizard page could look like after filling in all of the input variables with positional pre-processor information.

Page 5 (Map Simulation Model Output to Dakota Responses)

This page of the wizard is concerned with quantity of interest (QOI) extraction.

Again, the table is pre-populated with response labels extracted from your selected variable/response source file. Like with the pre-processing page, you may add or remove responses (not recommended, but possible).

The Script-Based Dakota Driver wizard knows how to extract QOIs from two potential sources:

• The standard output stream (i.e. console text) of your simulation model.
• A single destination file on your system (i.e. a log file). This is not recommended if you plan to run Dakota with multiple threads.

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

For each response label that is imported, click on its row in the table and select "Edit QOI Extractor". If you've never used a QOI extractor before, take a detour to learn about QOIs and how to extract them.

When you're done, this page of the wizard will look something like this:

Page 6 (Execution)

This last page of the wizard has several controls to help with the task of actually executing your simulation model.

Let’s go through the options one by one:

• Command Line Syntax This text field allows you to specify how to execute your simulation model on the command line. The driver wizard tries to be smart and provide you with some recommended default command line syntax, but most likely, you will need to change it.
  • There are two tokens you can use to perform runtime replacements of your command-line syntax – “${input_file}” and “${output_file}” Because our generated driver script will be creating new input files for the simulation model, we can’t hard-code an input file name, but we can use ${input_file} to tell the driver script to provide the newest input file to the simulation model, whatever that input file may be at runtime. ${output_file} works similarly, in that you can tell the driver script about the newest output file destination for the simulation model.
• Simulation Model Echo When your simulation model runs, it will often print to the console. You can instruct Dakota to include the simulation model's standard output stream in its own output stream if the "Echo simulation model’s stdout to Dakota console" box is checked. If your Dakota study will be running multiple iterations in parallel (which is recommended), you run the risk of many simulation model output streams becoming tangled in one console output window. To resolve this, you can prepend your simulation model’s output stream with numbers that indicate which Dakota iteration it's on. Use the second checkbox to achieve this.
• Dakota Interface There should only be a single checkbox in this field – “Create an interface manifest (.im) file.” What is an interface manifest? Because a Python script does not have any inherent mechanism for declaring what variables and responses it expects to handle for Dakota, this information can be stored in an interface manifest file that sits next to the generated Python script. Do not uncheck this box if you want to use the Dakota Study wizard next; that wizard requires that analysis drivers declare their compatible variables and responses.

Finishing

When you're all done, click Finish. If all went well, your new Python driver script should appear as a new file in your Dakota GUI project. It should also receive an additional interface manifest (.im) file.

If you know the Python language, you are now free to make additional modifications to the script if you so desire.

Workflow-Based Dakota Driver Wizard

The Workflow-Based Dakota Driver wizard creates a Dakota analysis driver that is an IWF workflow file. Workflow files provide you with a great degree of flexibility over how you pass input variables and output responses back and forth between Dakota and an external simulation model, all without the need to write any driver scripts.

Before beginning this wizard, you will need a file that declares your expected input variables and output responses. This could be a BMF file, or it could be a Dakota study, if you already have an appropriate Dakota study on hand.

To launch this wizard, go to File > New > Other. Then choose Dakota > Workflow-Based Dakota Driver.

On the first page of this wizard, give your workflow file a name and location.

On the second page of this wizard, choose a variable/response source file that will auto-generate this workflow’s inputs and outputs.

Now click Finish. That was easy!

If you need help building out the driver workflow you just created, refer to this tutorial.