There is a newer version of this document. To view the latest version, click here.

Pathfinder Monte Carlo User Manual

1. Monte Carlo Simulations

Pathfinder comes with a set of scripts to help you run Pathfinder from the command line. This document focuses on these scripts used to generate variations of an initial Pathfinder model for testing the effect of variability on the simulation results. Using this utility might be useful for testing the sensitivity to initial conditions (starting position, profile assignment, etc.) and/or to help with validation of distributions (normal, uniform, log-normal, etc.) used for input parameters to the model.

1.1. Usage

A typical usage of the Monte Carlo system is a three step process:

Run montecarlo_createcases.bat from the command prompt to generate some variations of a source model (as well as utility BAT files for running the models and collecting results).
Run all simulations by double-clicking the _run.bat script.
View results by clicking the _results.bat script.

The following examples are for different simulation scenarios that we used for testing the Monte Carlo utility. The reference to model.pth is just an example file name, you would need to create a simple model of your own.

1.1.1. Example 1: Randomize All Occupants

This command generates 20 variations of myfile.pth with randomized positions and profiles for all occupants.

"C:\Program Files\Pathfinder 2020\montecarlo_createcases.bat" myfile.pth 20

1.1.2. Example 2: Using an Exclude Filter

This command generates 20 variations of myfile.pth with randomized positions and profiles for all occupants except those under the "Base_Floor" group.

"C:\Program Files\Pathfinder 2020\montecarlo_createcases.bat" myfile.pth 20 -exclude=Occupants/Base_Floor

1.2. Known Limitations

You cannot modify model geometry or parameters related to it (stair width, rise/run, door width, etc.)

1.3. Previous Version

A previous version of this tool (released prior to Pathfinder 2020.1.0219) did not randomize any occupants directly under the Occupants node on the tree (only occupants in subgroups were randomized). This was to allow some basic level of control on which occupants were randomized, but this feature has been replaced by include/exclude filters (Chapter 3) in more recent versions of Pathfinder.

2. Process Overview

2.1. Generate Variations

Open a command window in the location of the .pth file (current working directory).

The basic command structure is:

<montecarlo_createcases.bat> <pathfinder filename> <number of variations> <addl. opts>

Example:

"C:\Program Files\Pathfinder 2020\montecarlo_createcases.bat" myfile.pth 20 -exclude=Occupants/First_Floor

This command will exclude any occupant whose ID contains the text "Occupants/First_Floor". An occupant’s ID is determined by its position in the Pathfinder tree (Navigation View). The separator for groups and object nodes is a forward slash.

2.1.1. Terminal Output

When the script is finished you will see output to the Terminal showing the status of every occupant in the model as shown in Figure 1.

Each ID string will be followed by three yes or no values:

Include: If this occupant included in the randomization process or not.
Rng Pos: If this occupant’s position will be randomized or not.
Rng Props: If this occupant’s profile and behavior properties will be randomized or not.

path mc scrn createcases output — Figure 1. Example of output from montecarlo_createcases.bat script.

2.1.2. Variations Folder

A new variations folder <pathfinder filename>_variations (Figure 2), containing all of the new cases and two batch script files.

path mc scrn variations folder — Figure 2. Example of variations directory contents

2.2. Run All Variations

To run all of the cases at once, navigate into the <pathfinder filename>_variations folder in File Explorer and double-click the _run.bat file. This will start a process to run all of the simulations in numerical order. Each simulation will output a brief summary to the Terminal window as shown in Figure 3. When the simulations are complete, the Terminal window will close.

path mc scrn summary output — Figure 3. Example summary output from the `_run.bat` script.

2.3. Plot Results

To create and view plots of Completion Times for All Occupants Figure 4 and Travel Distances for All Occupants Figure 5 double-click _make_plots.bat. The _make_plots.bat file is a gnuplot command file. It contains the plot data that has been extracted from the summary files for each run.

gnuplt scrn completion times — Figure 4. Example Completion Times gnuplot

gnuplt scrn travel dist — Figure 5. Example Travel Distance gnuplot

3. Additional Options

There are additional options that you can specify to change how the simulations are run and what information is included or excluded from the simulation.

See the additional options processing order diagram (Figure 6) to visualize the flow. Include is processed before exclude in all cases. Position and properties are processed separately.

--include=TEXT, --exclude=TEXT: Used to indicate sections of the occupant tree or specific occupants to include or exclude completely from the randomization. The entire path does not need to be included, since the filtering tests if any part of the occupant’s path contains the typed input.
--include_pos=TEXT, --exclude_pos=TEXT: Used to indicate sections of the occupant tree or specific occupants that will be included or excluded from the position randomization.
--include_props=TEXT, --exclude_props=TEXT: Used to indicate sections of the occupant tree or specific occupants that will be included or excluded from the profile randomization, which includes agent profiles and behaviors.
--room_rule=n: When randomizing position, this parameter controls which rooms an occupant is eligible to occupy.
Room options (n):
0 - (default) stay in current room
1 - all position randomized agents' current rooms
2 - any non-disabled occupiable room
--uniform_dist: Use this flag to change the positional distribution from random (default) to uniform, for debugging.
--rseed=s: Used to specify the value of the initial seed for the random number generator.

path mc graph processing order — Figure 6. Additional Options Processing Order

4. Support

Please email support@thunderheadeng.com if you have any questions about how to use this utility, or for new feature requests.