# Summary

This is a "start from scratch" example for building both an analysis driver and a Dakota study around a black-box simulation model.  You are encouraged to use the Dakota GUI in conjunction with this example.

# Description

The black-box simulation model used in this example is a *cantilever beam*, which can be thought of as a rigid structural element that extends horizontally and is supported at only one end.

The simulation model accepts seven input parameters:

 - the length of the beam, **L**
 - the width of the beam, **w**
 - the thickness of the beam, **t**
 - Young's modulus, **E**
 - the density of the beam, **p**
 - the horizontal load on the beam, **X**
 - the vertical load on the beam, **Y**

The simulation model produces three output responses:

 - the **mass** of the beam
 - the **stress** on the beam
 - the **displacement** of the beam

This problem is emblematic of most Dakota studies, in that we have a simulation model that takes input parameters and produces output responses, and we would like to use Dakota to study that model.

# Contents

- `cantilever` - the black-box simulation model representing the cantilever beam.  In reality, this is a Python script with the extension removed, so it would be invoked from the command-line as `python cantilever <input file>`, where <input file\> is the input data file for the simulation.
- `cantilever.template` - the templatized input file for the cantilever beam.  Note the presence of curly braces in the text of this file.  This file is primarily used in the **pre-processing** step of analysis driver logic.
- `CantileverBeam.yaml` - a lightweight definition for the input parameters and output responses of the cantilever beam. We choose to use YAML format here to recognize input parameters and output responses, but Dakota GUI also acknowledges JSON and INI formats.
- `externalProcess.log` - an example output log produced by running the cantilever black-box simulation.  This file could be generated by piping the standard output stream from `python cantilever <input file>` to a log file (for example:  `python cantilever <input file> > externalProcess.log`).  The information captured in this log is primarily used in the **post-processing** step of analysis driver logic.

# How to run the example

You are encouraged to use the Dakota GUI in conjunction with this example.

The Dakota GUI recommends **two possible approaches** for building a Dakota study around a black-box simulation model.  Which route you choose comes down to your use case / preferred method of working with analysis drivers and Dakota studies.

## Use Next-Gen Workflow to build a visual workflow for your driver

 - **Step 1.** [Read the strategy overview.](https://dakota.sandia.gov/sites/default/files/docs/latest_release/user-html/usingdakota/introduction/couplingtosimulations.html#couplingtosimulations-main)
 - **Step 2.** [Create inputs and outputs for your simulation model in the GUI.](https://dakota.sandia.gov/sites/default/files/docs/latest_release/user-html/usingdakotagui/introduction/simulationmodels.html#gui-simulation-models-overview)
 - **Step 3.** [Create a new Next-Gen Workflow using the Workflow-Based Dakota Driver wizard.](https://dakota.sandia.gov/sites/default/files/docs/latest_release/user-html/usingdakotagui/wizards/NewWorkflowDriver.html#wizards-newworkflowdriver-main)
 - **Step 4.** [Design a workflow that will execute your simulation model.](https://dakota.sandia.gov/sites/default/files/docs/latest_release/user-html/usingdakotagui/ngw/NextGenWorkflowTutorial.html#gui-nestedworkflowtutorial-main)
 - **Step 5.** [Create a new Dakota study using the Dakota Study Wizard, providing your workflow as the analysis driver.](https://dakota.sandia.gov/sites/default/files/docs/latest_release/user-html/usingdakotagui/wizards/NewDakotaStudy.html#wizards-newdakotastudy)
 - **Step 6.** [Choose the “Run As > Dakota (Workflow)” option to run your Dakota study.](https://dakota.sandia.gov/sites/default/files/docs/latest_release/user-html/usingdakotagui/running/DakotaRunConfiguration.html#gui-run-configurations-workflow)

If you would like to see a completed example of this approach, refer to the example located at:

`dakota-examples/official/gui/analysis_driver_tutorial/complete_ngw_driver`

## Use a script as your analysis driver

The Dakota GUI also supports the classic approach of invoking an executable script as the analysis driver (such as a Python script or a Bash script). If you would like to see a completed example of this approach, refer to the example located at:

`dakota-examples/official/gui/analysis_driver_tutorial/complete_python_driver`