# Summary

This is an example that studies a cantilever beam model using a Dakota centered parameter study.  Dakota and the cantilever beam model are connected via a Python driver script.

# Description of model

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.

# Description of analysis driver

Dakota does not know how to set up, run, or get output from a user's simulation.  That responsibility belongs to the *analysis driver,* which carries out those tasks on Dakota's behalf. In a typical study, Dakota runs the analysis driver one time for each evaluation, which is a mapping from a single point in input/parameter space to a corresponding point in response/output space.  The driver has three main responsibilities.

1. **Preprocessing:** Dakota provides parameter values to the driver by writing them to a parameters file.  It communicates the name of the parameters file as the first command line argument of the driver. In the preprocessing phase, the driver uses values it reads from the parameters file to construct valid input for the simulation.

2. **Execution:** The driver runs the user's simulation.

3. **Postprocessing:** In this phase, the driver extracts response information from simulation output and writes it to a correctly formatted Dakota results file. Dakota provides the name of the results file as the second command line argument to the driver.

Because Dakota does not directly interpret the driver and relies on the operating system and other tools on the user's system to execute it, the driver can be written in any programming language.  This example demonstrates a driver that was written in the Python programming language and was auto-generated by the Dakota GUI.

# 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.
- `CPS.in` - the Dakota study, which uses the `centered_parameter_study` method to study the cantilever beam model.
- `DakotaDriver.py` - the analysis driver for the Dakota study.  This Python script is responsible for transferring information between Dakota and the cantilever beam model.
- `DakotaDriver.py.im` - an "interface manifest" file, which is used by Dakota GUI.  The interface manifest declares which input parameters the Python driver script is capable of receiving, and what output responses it is expected to produce.
- `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.
- `qoi.py` - a library used by the main Python analysis driver script.  This library is responsible for extracting quantities of interest in the **post-processing** step.

# How to run the example

## Prerequisites (IMPORTANT!)

- This analysis driver will *only* work if Dakota's Python interfacing libraries are available on the **PYTHONPATH** environment variable.  For example, if you installed Dakota to `/home/dakota`, then the absolute path to the Python interfacing directory will be `/home/dakota/share/dakota/Python`, and this must be available on PYTHONPATH for the Python driver script to work correctly. [You can learn more about PYTHONPATH here.](https://docs.python.org/3/using/cmdline.html#environment-variables)
- Additionally, you may be required to alter the line `analysis_drivers "python3 -m DakotaDriver"` in the `CPS.in` input file. If you are using Python 2.7 or older, or if `python3` is aliased to `python`, you may need to change this line to the following: `analysis_drivers "python -m DakotaDriver"` 

## Run on command line

    $ dakota -i CPS.in

## Run in Dakota GUI

After importing this example project into the GUI, right-click the CPS.in file, and choose `Run As > Dakota` from the context menu.

# Further Reading

This example was developed from the example available at `dakota-examples/official/gui/analysis_driver_tutorial/begin`.