Table of Contents

1. Introduction
2. Dakota Visual Editor
3. Dakota Text Editor
4. Tree in the Project Navigator view

Introduction

Once you have a Dakota input file imported into the GUI, there are many available options for inspecting and editing it.

Dakota Visual Editor

The Dakota Visual Editor is a powerful alternative to editing Dakota input files in a text editor. Gone are the days of manually tinkering with long number arrays, or hoping that variables and responses are active and indexed correctly.

If the Dakota Visual Editor is not configured as your default editor of Dakota input files, right-click a Dakota input file and choose "Open With > Dakota Visual Editor". Otherwise, simply double-click the file.

The Top Level of a Dakota Input File

When first opened, the Dakota Visual Editor shows you the top level of a Dakota input file:

The hiearchical relationship of Dakota blocks is made explicit through indentation. Clicking on any Dakota block will take you to the editor for that block.

After diving into a specific Dakota block, the action bar along the top of the editor will update:

The left and right arrow buttons will allow you to traverse to the previous or next Dakota block in the input file, respectively. The up arrow will allow you to return to the top of the Dakota input file.

Also, note that there are "?" buttons throughout the editors for specific Dakota blocks (typically to the far-right of an individual editor control). The "?" button will take you to the appropriate page in the Dakota Reference Manual for that keyword.

When you are done making changes to the Dakota input file, simply save the file as you would with any other text editor.

Environment, Model, and Interface Blocks

For the environment, model, and interface blocks, hierarchical keyword editors are displayed, allowing you to edit the block using these editor controls. Here is an example environment block:

Variable Blocks

The editor for a variables block is slightly more involved and warrants some additional explanation.

• Variables ID This field controls the ID of your variables block.
• Table Button Bar There's a horizontal row across the top of the variable table that allows you to manipulate table data.
  • Add New Variable Adds a new variable to your variable block.
  • Edit Variable Edits the properties of the currently selected variable.
  • Remove Variable Removes the currently selected variable from the block.
  • 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.
  • Auto-Visualize Variable For variable types that have an uncertainty/probability functions associated with them, this button allows you to visualize the curve (according to the properties set for this variable) in the Chartreuse Sandbox View.
  • Open Dakota Reference Manual for Variable Category For the currently selected variable's category, open the appropriate page in the Dakota Reference Manual.
  • Active variables dropdown Allows you to manually specify the active variable set of this Dakota variables block. Refer to the variables section of the Dakota Reference Manual for more information on active variables.
  • Variable Domain Located below the table, this dropdown allows you to manually specify a "mixed" or "relaxed" domain for this variables block.

Within the table, the columns are as follows (from left to right):

• (Active) If the variable is active according to the overall specification of this Dakota input file, a lit-up lightbulb icon will be displayed; otherwise, the lightbulb icon will appear dimmed. It is not possible to directly change the active/inactive state of a variable. Refer to the variables section of the Dakota Reference Manual for more information on active variables.
• # The Dakota spec order for this variable. Dakota variables are ordered first by variable category and then by user-customized ordering within that category.
• Variable The name (or "descriptor") of the variable.
• Category The category that this variable belongs to. Changing the category will automatically cause a reordering of Dakota variables based on the new category position of this variable.

Variable Properties Dialog

Once a variable has been assigned to a category (such as continuous_design), you can access that variable category's properties. 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.

View Variable Table by Category

Along the top action bar of the Dakota Visual Editor, you may also notice a "View category" dropdown. This allows you to dive into viewing the properties of a single variable category:

Note that we are still in the same variables block, but the view has changed. In this screenshot, we're only viewing continuous design variables. The other continuous state variables in this example have been hidden from view. In addition, the properties of those continuous design variables have been exposed as table columns. From this view, if you want to edit the properties of an individual variable, you no longer have to push the "Edit" button along the top of the table - you can simply directly edit the property using the table.

Response Blocks

• Responses ID This field controls the ID of your responses block.
• Response Type Choose the type of response for this responses block.
• Gradient Choose the type of gradient for this responses block.
• Hessians Choose the type of hessian for this responses block.
• Table Button Bar There's a horizontal row across the top of the response table that allows you to manipulate table data.
  • Add New Response Adds a new response to this responses block.
  • Edit Response Edits the properties of the currently selected response.
  • Remove Response Removes the currently selected response from the block.
  • Response Ordering within Category Dakota responses are ordered first by response category (either "scalar" or "field" within the specified type of response), and then by user-customized ordering within that category. This button allows you to configure the latter.
  • Open Dakota Reference Manual For the currently selected responses's category, open the appropriate page in the Dakota Reference Manual.

Within the table, the columns are as follows (from left to right):

• Response The name (or "descriptor") of the response.
• Category The category that this response belongs to. Changing the category will automatically cause a reordering of Dakota responses based on the new category position of this variable.

Note: It is not currently possible to specify nonlinear equality or inequality constraints for Dakota responses blocks using the Dakota Visual Editor.

Method Blocks

Dakota has a multitude of method types, so we can't cover all of them in this manual. But we will take a look at one method editor that clearly demonstrates the benefits of using the Dakota Visual Editor: centered parameter studies.

Classically, a method block specifying centered_parameter_study would be written as follows in a Dakota input file:

The step_vector keyword is followed by a series of values, where each value relates to the variable that is in that same index in the variables block. Likewise for the steps_per_variable keyword.

For seven variables (as shown here), it is somewhat trivial (though not completely error-proof) to glance up and down between the method block and the variables block to determine which number goes with which variable. But as the number of variables increases, this manual verification process becomes more and more error-prone.

Worse still, if there is a specification of active variables for this Dakota study (that is, some variables are inactive), the index in the method block corresponds to the index from the list of active variables, NOT the full list of all variables from the variables block. In short, visually determining which method keyword value corresponds to what variable becomes much harder for active variable sets.

All of this is handled for us if we use the centered parameter study editor provided by the Dakota Visual Editor:

There is now no longer a need to keep track of values by index. The step vector values and steps-per-variable values are visually associated with the proper variable, simply by being on the same row of the table. Also, each variable's initial value is provided as well, to give additional context that can inform analysts what to choose for the step vector and steps-per-variable columns.

Note: Not all Dakota methods are supported with custom editors. However, the Dakota team is working to add more and more custom method editor support with each release. As of version 6.13.0 of Dakota GUI, the following methods are supported with custom method editors:

• centered_parameter_study
• hybrid
• list_parameter_study
• multidim_parameter_study
• multilevel_sampling
• sampling
• vector_parameter_study

Dakota Text Editor

The Dakota text editor is the most traditional way of editing a Dakota input file. While not recommended for complex Dakota studies, the text editor can be handy if you just need to make a small adjustment to your Dakota input file.

If the Dakota Text Editor is not configured as your default editor of Dakota input files, right-click a Dakota input file and choose "Open With > Dakota Text Editor". Otherwise, simply double-click the file.

Error Markup

The Dakota GUI’s text editor provides some basic error marking functionality that can help with malformed Dakota input files. For example, in this screenshot, we have a continuous_design section of a variables block, stating that it will have 3 variables. However, only 2 variables are specified below; this prompts an error to be displayed, warning us about the discrepancy. Keywords relevant to the error are marked with red underlines. Tooltip text help (i.e. the pale yellow box pictured here) can be viewed if you hover over the red X icons to the left; doing this provides more information about what is specifically wrong with your file.

Completion Proposals

Completion proposals are context-sensitive recommendations provided by the Dakota text editor. If you are writing a Dakota text file, completion proposals can tell you which keywords are legally allowed to come next. Completion proposals can also give you clues about values to use for new id_* and *_pointer keywords.

Suppose we start with an empty environment block.

With the text cursor on "environment," press Ctrl+Space (Command+Space on Mac.) The following context menu will appear with recommendations for which keywords to include in your environment block.

As stated earlier, if you have block pointers specified elsewhere in your study, completion proposals can also recommend which blocks to point at:

Block Recipes

If you want to wholesale replace a Dakota block with another block that has reasonable defaults for a different situation, right-clicking on a top-level keyword in the Dakota text editor will enable a "Replace Block with Recipe" context menu option:

A situation where this might be useful is for hooking a Dakota study up to a workflow file as your chosen Dakota analysis driver. You can also use this feature to switch to a different Dakota method, without disturbing the rest of the input file.

DPREPRO Markup

The Dakota text editor respects some DPREPRO-style markup. Orange bold text is used to indicate markup syntax:

However, there are some limitations to using DPREPRO markup in the Dakota text editor:

• The markup must apply to individual parameter values of Dakota keywords, as shown above. Markup cannot be used in place of Dakota keywords themselves, and a single markup token cannot be applied across multiple parameter values at once.
• % statements are used in DPREPRO syntax to insert blocks of Python code that should be executed at runtime. Single-line % statements are supported in the Dakota text editor, but blocks of Python code surrounded by % characters are not supported yet.

Learn more about the DPREPRO pre-processing tool in Section 10.8 of the Dakota User's Manual.

Tree in the Project Explorer view

A Dakota input file can be expanded in the Project Explorer view's tree to reveal its content hierarchically:

"New Keyword" context menu option

With a Dakota study expanded in the Project Explorer, right-click a Dakota keyword and choose "New Keyword." A sub-context menu will pop out with available keywords at the point in the Dakota study you clicked on. Choosing a keyword from this sub-context menu will automatically add it to your Dakota study.