Tutorial 1: Simulation Ensemble Creation and Execution¶

Creating a simulation ensemble using the variables’ distributions¶

In this tutorial, a simulation ensemble is created (using FOQUS) and run.

The FOQUS file for this tutorial is Rosenbrock_no_vectors.foqus, and this file is located in: examples/tutorial_files/UQ/Tutorial_1

Note

The examples/ directory refers to the location where the FOQUS examples were installed, as described in Install FOQUS Examples.

From the FOQUS main screen, click the Session button and then select Open Session to open a session. Browse to the folder shown above, and select the “Rosenbrock_no_vectors.foqus” file (Figure Home Screen).

Home Screen¶
Opening this file loads a session that has a flowsheet with one node (Figure Flowsheet for Rosenbrock Example). See Section Tutorial 1: Creating a Flowsheet for a detailed example of creating a flowsheet.

Flowsheet for Rosenbrock Example¶
Click the Uncertainty button (Figure Uncertainty Quantification Screen).

Uncertainty Quantification Screen¶
Click Add New to create a new simulation ensemble.
The Add New Ensemble dialog displays (Figure Add New Ensemble Dialog, Flowsheet Option). The “Use flowsheet” option should be enabled.
This item describes additional features and is provided for information only. It is not intended to be followed as part of the step-by-step tutorial.

An alternative is to use an emulator by selecting “Use emulator.” This alternative is preferred if the actual simulation model is too computationally expensive to be practical for a large number of samples. This option enables the user to trade off accuracy for speed by training a response surface to approximate the actual simulation model. If this option is selected (Figure Add New Ensemble Dialog, Emulator Option), the user needs to provide a training data file containing a small simulation ensemble generated from the actual simulation model. This training data file should be in the PSUADE full file format (see section File Formats).
- Click Browse and select the training data file with which to train the response surface. The inputs, outputs and response surface type is read from the training data and populated accordingly on this dialog box.
- Select Output(s) of Interest. To select multiple outputs, the user can use Shift + Click to select a range, or use Ctrl + Click to select/deselect individual outputs.
Click OK.

Add New Ensemble Dialog, Flowsheet Option¶

Add New Ensemble Dialog, Emulator Option¶
This displays the Simulation Ensemble Setup dialog box (Figure Simulation Ensemble Setup Dialog, Distributions Tab ) that prompts the user for options specific to the creation of input samples.
Within the Distributions tab, the Distributions Table has all the inputs from the flowsheet node, each displayed in its own row.
1. Click the All Variable button.
2. Change the Type of “x2” to “fixed.”
3. Enter 5 into the Default column for “x2.”
Subsequently, other cells in the row are enabled or disabled according to the type selection.

Simulation Ensemble Setup Dialog, Distributions Tab¶

In this dialog, extra options that are available related to simulation ensemble setup are discussed.
- Change the PDF of “x6” by exploring the drop-down list in the PDF column of the Distributions Table. The drop-down list is denoted by box (9c) in Figure Simulation Ensemble Setup Dialog, Distributions Tab, PDF Selection. If any of the parametric distributions are selected (e.g., “Normal”, “Lognormal”, “Weibull”), the user is prompted to enter the appropriate parameters for the selected distribution. If non-parametric distribution “Sample” is selected, the user needs to specify the name of the sample file (a CSV or PSUADE sample format is located in Section File Formats) that contains samples for the variable “x6.” The user also needs to specify the output index to indicate which output in the sample file to use. The resulting simulation ensemble would contain “x6” samples that are randomly drawn (with replacement) from the samples in this file.
  
  Simulation Ensemble Setup Dialog, Distributions Tab, PDF Selection¶
- Alternatively, select Choose sampling scheme (box (8) of Figure Simulation Ensemble Setup Dialog, Distributions Tab), and try selecting “Load all samples from a single file.” With this selection, a new dialog box prompts the user to browse to a PSUADE full file, a PSUADE sample file, or CSV file (all formats are described in Section File Formats) that contains all the samples for all the input variables in the model.
Both of these options offer the user additional flexibility with respect to characterizing input uncertainty or generating the input samples directly.
Once complete, switch to the Sampling Scheme tab (Figure Simulation Ensemble Setup Dialog, Sampling Scheme Tab).

Simulation Ensemble Setup Dialog, Sampling Scheme Tab¶
Select a sampling scheme with the assumption that the user is unsure which sampling scheme to use, but wants to perform some kind of response surface analysis. This example helps the user find a suitable one.
1. Click For response surface analysis. Note the list on the right changes accordingly.
2. Select “Latin Hypercube” from the list on the right.
To generate 500 samples, change the value in “# of samples.” Some sampling schemes may impose a constraint on the number of samples. If the user has entered an incompatible sample size, a pop-up window displays with guidance on the recommended samples size.
Click Generate Samples to generate the sample values for all the variable input parameters. On Windows, if the user did not install PSUADE in its default location (C:Program Files (x86)psuade_project 1.7.1binpsuade.exe) and the user did not update the PSUADE path in FOQUS settings (refer to Section Settings), then the user is prompted to locate the PSUADE executable in a file dialog.
Once the samples are generated, the user can examine them by clicking Preview Samples. This displays a table of the values, as well as the option to view scatter plots of the input values. The user can also select multiple inputs at once to view them as separate scatter plots on the same figure.
When finished, click Done.
The simulation ensemble should be displayed in the Simulation Ensemble Table. If the user would like to change any of the parameters and regenerate a new set of samples, simply click the Revise button.
Next, calculate the output value for each sample. Click Launch. The user should see the progress bar quickly advance, displaying the status of completed runs (Figure Simulation Ensemble Added).

Simulation Ensemble Added¶
Next, look at the output.
1. Click Analyze for “Ensemble 1” (Figure Simulation Ensemble Evaluation Complete).
  
  Simulation Ensemble Evaluation Complete¶
2. Step 1 of “Analysis” (bottom page), the user selects Ensemble Data (Figure Simulation Ensemble Analysis).
  
  Simulation Ensemble Analysis¶
3. Step 2 of “Analysis” is to select “Rosenbrock.f” (Figure Simulation Ensemble Analysis).
4. Step 3 of “Analysis” is to keep the analysis method as “Uncertainty Analysis” and then click Analyze. The user should see two graphs displaying the probability and cumulative distributions plots (Figure Uncertainty Analysis Results). Users should keep in mind these figures are intended to show what type of plots they would get, but they should not expect to reproduce the exact same plots.
Uncertainty Analysis Results¶

Prior to this, the “Rosenbrock” example was selected to illustrate the process of creating and running a simulation ensemble because simulations complete quickly using this simple model. But from this point on, the adsorber subsystem of the A650.1 design is used as a motivating example to better illustrate how one would apply UQ within the context of CCSI.

A quick recap on our motivating example: The A650.1 design consists of two coupled reactors: (1) the two-stage bubbling fluidized bed adsorber and (2) moving bed regenerator, in which the output (outlet of sorbent stream) from one reactor is the input (inlet) for the other. The performance of the entire carbon capture system is obtained by solving these two reactors simultaneously, accounting for the interactions between the reactors. However, it is also necessary to study the individual effects of the adsorber and the regenerator without the side effects of their coupling since the two reactors display distinct characteristics under different operating conditions. Thus, the Process Design/Synthesis Team has given us a version of the A650.1 model that can be run in two modes: (1) coupled and (2) decoupled. In this section, analysis results are presented from running the A650.1 model using the decoupled mode and examining the adsorber in isolation from the regenerator.

Automatically running FOQUS for a set of user-defined input conditions¶

In this tutorial, we will show you how to automatically run a set of user-defined input conditions in FOQUS.

This procedure will require the user to specify the input conditions in a CSV (comma-separated values) Excel file.

We will use a simple example to show the procedure.

Open FOQUS.
Go to the “Session” tab, and under “Session Name” type: basic_example (please see Figure Specifying the Session Name).

Go to the “Flowsheet” tab, and click the “Add Node” button (“A” in Figure Inserting a Node and Specifying the Inputs).

Inserting a Node and Specifying the Inputs¶

Insert a node called “example” (without the quotes) (“B” in Figure Inserting a Node and Specifying the Inputs).
Open the Node Editor by clicking the Toggle Node Editor button (“C” in Figure Inserting a Node and Specifying the Inputs).
Under the Node Editor, click “Input Variables” and the green “+” button (“D” in Figure Inserting a Node and Specifying the Inputs).
Insert input variables x1 and x2 (“E” in Figure Inserting a Node and Specifying the Inputs).
For x1, specify the value, default, minimum, and maximum as 3, 3, -10, and 10, respectively (“E” in Figure Inserting a Node and Specifying the Inputs).
For x2, specify the value, default, minimum, and maximum as 4, 4, -10, and 10, respectively (“E” in Figure Inserting a Node and Specifying the Inputs).
Under the Node Editor, click “Output Variables” and the green “+” button (“A” and “B” in Figure Specifying the Outputs).

Specifying the Outputs¶

Insert output variables y1 and y2 (“C” in Figure Specifying the Outputs).
Under the Node Editor, click “Node Script” (“A” in Figure Inserting the Equations).

Inserting the Equations¶

In the first line under “Node Script (Python Code)”, type: f[‘y1’] = 2 * x[‘x1’] + 3 * x[‘x2’] (“B” in Figure Inserting the Equations).
In the second line under “Node Script (Python Code)”, type: f[‘y2’] = 3 * x[‘x1’] + 5 * x[‘x2’] (“B” in Figure Inserting the Equations).
Open Microsoft Excel.
Type example.x1 and example.x2 as the headings in Cells A1 and B1 (please see Figure Specifying the Inputs in Excel).

Specifying the Inputs in Excel¶

Type 1, 3, 5, 7, 9 under example.x1 (please see Figure Specifying the Inputs in Excel).
Type 0, 2, 4, 6, 8 under example.x2 (please see Figure Specifying the Inputs in Excel).
Save the Excel file, with file name “example_samples” (without the quotes), and “CSV (MS-DOS)” as the file type .
Return to FOQUS, and go to the “Uncertainty” tab (“A” in Figure The Uncertainty Tab in FOQUS).

The Uncertainty Tab in FOQUS¶

Click the “Add New” button (“B” in Figure The Uncertainty Tab in FOQUS).
Select “Use flowsheet”, and click “OK” (“C” and “D” in Figure The Uncertainty Tab in FOQUS).
Select “Load all samples from a single file” (“A” in Figure Uploading the CSV File Containing the Inputs).

Uploading the CSV File Containing the Inputs¶

Click “Browse”, and select the “example_samples” CSV file (“B” in Figure Uploading the CSV File Containing the Inputs).
Click “Done” (“C” in Figure Uploading the CSV File Containing the Inputs).
The user-specified inputs should appear in the “Ensemble” table (please see Figure The User-Specified Inputs in the Uncertainty Tab).

The User-Specified Inputs in the Uncertainty Tab¶

Run these inputs by clicking the “Launch” button (please see Figure The User-Specified Inputs in the Uncertainty Tab).
After the runs are finished, the results are shown in the table at the bottom of the “Uncertainty” tab (please see Figure The Results of the Runs in the Uncertainty Tab).

The Results of the Runs in the Uncertainty Tab¶

The user can also view the results in the Flowsheet tab by clicking the “Results and Filtering” button (“A” in Figure The Results of the Runs in the Flowsheet Table).

The Results of the Runs in the Flowsheet Table¶

The Flowsheet Table contains the results (“B” in Figure The Results of the Runs in the Flowsheet Table).