Results Scripting

1. Overview

This tutorial is intended for users of the Thunderhead Results Viewer that require more complex or repetitive post-processing than what is available in the standard Results UI. It will demonstrate the basics of how to use the Results Scripting Engine. You will learn how to use the Results Scripting Engine to load custom user scripts, run them, and view any generated visualizations in the Results UI.

2. Before Starting

Before beginning this tutorial:

3. Introduction

The Results Scripting Engine allows Results to run user-developed Python scripts for specialized post-processing of simulation data. These scripts can create any number of complex visualizations. For simplicity’s sake, this tutorial will only cover the basics of loading and running scripts, and viewing any visualizations created by the script. More advanced scripts can be created and executed using the same steps laid out below, using any combination of Python packages, including the theng package provided by Thunderhead Engineering.

4. Using the Results Scripting Engine

Using the Results Scripting Engine is very straightforward. These steps will show you the basics of using this new feature by using the theng Getting Started Files you downloaded above as an example.

4.1. Loading a Script

The first step to using the Results Scripting Engine is to load a written script in to the Results Visualization. To load a script in to a Results Visualization:

1. Locate and open the example_evac.pfrv visualization file created as part of your work through the theng Getting Started Guide. It should be in getting-started/models/Pathfinder/example_evac.
2. Locate the User Scripts entry of the Results Tree.
3. Right-click the User Scripts entry of the Results Tree.
4. Click Load Python Script.
5. In the File Dialog that opens, find the exit-time.py script. It should be in getting-started/scripts.
6. Select the exit-time.py script and click Open.

The script should now be loaded in as a new entry in the User Scripts section of the Result Tree.

4.2. Running Scripts

Running Scripts in the Thunderhead Results Viewer is just as simple as loading a script. Scripts can be run in 3 ways:

1. Double-click the script entry in the Results Tree
2. Right-click the script and select Run Script
3. Select multiple scripts in the Results tree, then right-click and select Run Script to run multiple scripts

Try this now using the script you loaded in the previous step.

4.3. Viewing Visualizations

After running the script, you should notice a new entry in the Results Tree. This script created a pair of visualizations of simulation data and communicated information about those visualizations automatically to the Results Scripting Engine. The Results Viewer then automatically created references to those visualizations and associates them with the script that created them. You can view these visualizations in the Results UI in 2 ways:

1. Double-clicking the new visualizations entries in the Results Tree
2. Double-clicking the User Scripts entry in the Results Tree to show all visualizations created by User Scripts

This will open the visualizations in a new window for user review. Note how one of the visualizations created by the exit-time.py script is interactive. This is not a special feature of the Results Scripting Engine, but rather of the plotly plotting library used in the script. The Results Viewer simply loads the HTML file generated by plotly, which has interactive elements built in to it. You can create and load any HTML file that you want from a user script, and view it in the Results Viewer.

5. Conclusion

You should now be familiar with how to load, run, and view the results of scripts using the new Results Scripting Engine. Hopefully you also have an appreciation of how versatile this tool can be for your workflows.

To download the most recent version of Pathfinder that includes this new feature, please visit the Pathfinder support page and click the link for the current release. Please contact support@thunderheadeng.com with any questions or feedback regarding our products or documentation.