Reading Time: 9 minutes
Created with software version: 2023.3

1. Overview

This tutorial will demonstrate how to use the scenarios feature. You will learn how to create scenarios, edit object properties and disable objects between scenarios, and run all scenarios in the model.

2. Before Starting

Before beginning this tutorial:

3. Using Scenarios

The ability to create scenarios is a powerful feature in PyroSim intended to improve user workflow. Scenarios allow the use of a single geometry model to create and run multiple different simulations with different fire and object configurations. For example, when designing design fire scenarios per NFPA 101 section 5.5 (NFPA 2021) up to 8 different scenarios can be required for compliance. The scenarios feature reduces the time and effort required to model and simulate these different scenarios.

Scenarios reduce the amount of hard drive space required to store a large project, reduce the number of PyroSim files to manage/update, and make it easier to run batches of simulations.

This section will teach the basics of scenarios, and walk through a simple demonstration of how to use the Edit Scenarios dialog in PyroSim to create, edit, and activate a scenario.

3.1. Opening the Edit Scenarios Dialog

To begin, open Getting Started - Scenarios.psm linked at the top of this tutorial. To open the Edit Scenarios dialog, click the pyro ui icon scenarios Edit Scenarios icon on the main toolbar. Figure 1 shows the dialog that should appear.

pyro ui dialog edit scenarios
Figure 1. Screenshot of the Edit Scenarios dialog

The tree on the left-hand side of the dialog shows all of the scenarios defined in this model. By default, there is only one scenario defined, and it is automatically selected when the dialog is opened for the first time.

At the top of the right-hand side of the dialog, the Scenario ID of the selected scenario is listed and below, the Description for the selected scenario is given. The Description the text field can be edited to help manage and keep notes about the specifics of each scenario.

Below the Description field is the Disabled Objects text box. This text box will list all of the objects that are disabled for the selected scenario. This text box will be covered in more depth later in this tutorial.

3.2. Creating New scenarios

To create new scenarios, simply click the New button in the Edit Scenarios dialog. For this example:

  1. Click New in the Edit Scenarios dialog.
  2. In the New Scenario dialog, name the scenario Ground Floor.
  3. In the Based On dropdown, select Default.
  1. Click OK.

The above steps will have created the Ground Floor scenario in the Edit Scenarios dialog tree. Repeat steps 1-4, this time naming the new scenario Second Floor.

Once the two new scenarios are created, select the Default scenario, and click Delete. Now, the Ground Floor and Second Floor scenarios should be the only two scenarios in the tree, shown in Figure 2.

pyro ui dialog scenarios modified scenarios
Figure 2. Edit Scenarios dialog with the two new scenarios created.

With the Edit Scenarios dialog still open, select the Ground Floor scenario, and then click Activate. In the PyroSim menu bar, the Ground Floor scenario has been activated in the Active Scenario dropdown, located next to the pyro ui icon scenarios Edit Scenarios icon and shown in Figure 3. The scenario dropdown can be used to select which scenario is active without opening the Edit Scenarios dialog.

pyro ui icon scenarios dropdown
Figure 3. Screenshot of the scenarios icon and dropdown

In the Description field of the Ground Floor scenario, enter the following description, then click Apply to save the changes:

This scenario is a ground floor hallway fire, with no fire suppression system.

Likewise, in the Description field of the Second Floor scenario, enter the following description, then click Apply to save the changes:

This scenario is a second floor room fire, with a simple fire suppression system.

4. Editing Scenarios

Now that the new scenarios have been created, it is time to start defining them. The main way that scenarios are defined is through the selectve disabling of objects. The following steps will demonstrate how to disable objects and how to switch between the different scenarios.

4.1. Disabling objects

  1. With the Ground Floor scenario active, change the model’s floor view to 2nd in the Floor View dropdown. This will give a clear visual representation of the effects of the Scenarios feature.
  2. In either the navigation tree or the 3D window, right click on the vent labeled Burner Vent - 2nd.
  3. In the pop-up menu, click Disable Object(s). Note how the vent disappears from view in the 3D window and is struckthrough in the navigation tree.
  4. Repeat steps 2-3 with the devices labeled Thermocouple - 2nd, SD - 2nd, and Sprinkler - 2nd.

With the second floor objects disabled, the Ground Floor scenario is now different than the Second Floor scenario. In the Active Scenario dropdown, switch between the two scenarios. The second floor objects are still active and visible in the Second Floor scenario, but not in the Ground Floor scenario.

To finalize the two scenarios, switch to the Second Floor Scenario, and disable the Burner Vent - Ground, SD - Ground, and Thermocouple - Ground objects.

4.2. Scenario Overview

To get an overview of the two scenarios, open the Edit Scenarios dialog by clicking the pyro ui icon scenarios Edit Scenarios icon. In the scenarios tree, select the Ground Floor scenario. The Disabled Objects text box, mentioned in Section 3.1, now shows all of the objects that were disabled in this scenario. Selecting the Second Floor scenario in the scenario tree will update the list to represent only the objects disabled in the Second Floor scenario.

4.3. Updating Object Properties

Currently, scenarios only explicitly track the enabling and disabling of objects. To modify an object parameter in a scenario, the object must be duplicated, the parameter in the duplicate must be modified, and the original object must be disabled in the scenario. The following will walk through a brief example of this by adjusting the heat release rate of the fire in the Second Floor scenario.

  1. With the Second Floor Scenario active, right-click the vent labeled Burner Vent - 2nd.
  2. Click Copy/Move.
  3. In the Translate dialog, select the Copy mode, then click OK. This should duplicate the vent and create Burner Vent - 2nd01.
  4. Rename Burner Vent - 2nd01 to Burner Vent 2000 - 2nd.
  5. Double-click the surface labeled Fire in the navigation tree to open the Edit Surfaces dialog. Note that the Heat Release Rate Per Unit Area (HRRPUA) is \(1000 \frac{kW}{m^2}\).
  6. Click New to create a new surface.
  7. Name the new surface Fire - 2000, and use the Fire surface as the template surface, as shown in Figure 4.
  8. In the Heat Release tab of the new surface, set the HRRPUA to \(2000 \frac{kW}{m^2}\), then click OK.
  9. Double-click the Burner 2000 - 2nd vent, set the surface to the new Fire - 2000 surface, then click OK. Note that this vent has an area of \(1.0 m^2\), resulting in a new heat release rate of \(2000 kW\).
  10. Right-click the Burner Vent - 2nd vent, and click Disable Object(s).
  11. Switch to the Ground Floor scenario.
  12. Right-click the Burner Vent 2000 - 2nd vent, and click Disable Object(s).
pyro ui dialog new surface template surface
Figure 4. Creation of a new surface using the Fire surface as a template

The Second Floor scenario now has a new heat release rate of \(2000 kW\) for the fire. This process can be replicated with any number of other object properties, it is not limited to just HRRPUA or vents.

5. Running the scenarios

Now that the two scenarios have been created and defined, it is time to run them. Scenarios can be run individually like any other model by switching between scenarios in the Active Scenario dropdown, then running in Serial, Parallel, or Cluster mode, but running individually like this can be time consuming when running a large number of scenarios or when running a large simulation. Running individually like this will also overwrite the same results file every time. This is a good method to preview the results of a single scenario, but not for running the simulations. Instead, use the Export Scenarios feature to run all of the scenarios sequentially.

5.1. Exporting the Scenarios batch script

To export the scenarios batch script:

  1. Click the File button in the menu bar.
  2. Hover the mouse cursor ove the Export button, then click Export Scenarios in the pop-out menu.
  3. In the Save dialog, select a location to save the model and the exported batch script, then click OK.
  4. Once the model and script have been saved (this may take a minute), a new Windows Explorer window will open with the run_scenarios-Getting_Started_-_Scenarios.bat file highlighted.

This batch script will run all of the scenarios PyroSim just generated and saved. The individual FDS and other configuration files are located inside of folders in the same directory as the batch file.

5.2. Viewing and Editing the Batch Script

In the Windows Explorer, right-click the batch script and click Edit. A notepad window should pop-up and show a script similar to the following:

@ECHO off
@ECHO [%~n0] Beginning at %time%

SET PATH=%PATH%;C:\Program Files\PyroSim 2020\fds
SET PATH=%PATH%;C:\Program Files\PyroSim 2020\fds\mpi


ECHO [%~n0] Scenario "Ground Floor" beginning at %time%
PUSHD Getting_Started_-_Scenarios-Ground_Floor
runfds.exe mpiexec.exe -n 1 -localonly fds.exe Getting_Started_-_Scenarios.fds

ECHO [%~n0] Scenario "Second Floor" beginning at %time%
PUSHD Getting_Started_-_Scenarios-Second_Floor
runfds.exe mpiexec.exe -n 1 -localonly fds.exe Getting_Started_-_Scenarios.fds

ECHO [%~n0] Completed at %time%

The first 11 lines of the batch script set some environment variables for FDS and MPI, and print some output to the shell window when it is run. To learn more about the MPI variables and what they do, see this post.

The rest of the code handles running each scenario. The script moves the working directory into the scenario folders, runs each scenario, then move back to the root directory of the project. The variables in this script can be modified to improve simulation time according to the post above and the FDS User Guide.

By default, the batch file is configured to run each simulation in sequence using a configuration largely identical to PyroSim’s Run Parallel command. It uses the program runfds.exe, which is a convenience application bundled with PyroSim that launches fds.exe with "below normal" operating system priority – a quality of life feature for users that continue using their PC while the simulations are running with negligible performance impact for unattended runs.

5.3. Running the batch script

To run the batch script, double click the batch script in the Windows Explorer, or run it via command line. This will open a new command prompt window and begin the simulations. When the simulations are complete, view the 3D results by opening the *.smv files in the individual scenario directories created by PyroSim above.

6. Conclusion

You should now be familiar with how to create scenarios, disable objects and edit properties between scenarios, and run all scenarios in the model.

To download the most recent version of PyroSim, please visit the PyroSim support page and click the link for the current release. If you have any questions or feedback regarding the scenarios feature, please contact

7. Bibliography

NFPA. 2021. “NFPA 101 - Life Safety Code.” National Fire Protection Association.