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

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 parameter 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:

  1. 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).
  2. Run all simulations by double-clicking the _run.bat script.
  3. 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

  1. You cannot modify model geometry or parameters related to it (stair width, rise/run, door width, etc.)
  2. There is currently a known bug with how the _run.bat file is generated that can cause it to exceed the Windows command length limit. If you use the _run.bat file and it does not appear to work, you can work around this issue by shortening the filename of your Pathfinder model.

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 will generate the following files:

Completion Times for All Occupants (s).csv
This file contains data on the completion times of occupants across all variations. Each column’s data is described below.
  • ID: Unique identifier for each variation.
  • MIN: The minimum completion time for all occupants, as reported in the Summary Report.
  • MAX: The maximum completion time for all occupants, as reported in the Summary Report.
  • LOW: The AVG completion time minus one Standard Deviation.
  • HIGH: The AVG completion time plus one Standard Deviation.
  • AVG: The AVG completion time for all occupants.
  • STDDEV: The standard deviation about the average.
Travel Distances for All Occupants (m).csv
This file contains data on the total travel distances for all occupants across all variations. Each column’s data is described below.
  • ID: Unique identifier for each variation.
  • MIN: The minimum travel distance for all occupants, as reported in the Summary Report.
  • MAX: The maximum travel distance for all occupants, as reported in the Summary Report.
  • LOW: The AVG travel distance minus one Standard Deviation.
  • HIGH: The AVG travel distance plus one Standard Deviation.
  • AVG: The AVG travel distance for all occupants.
  • STDDEV: The standard deviation about the average.
Completion Times for All Occupants (s).html
This file contains a plot of the data written to Completion Times for All Occupants (s).csv. Double-clicking this file will open the plot, shown in Figure 4, in your default browser window. For each variation, the thin plotted line plots the range of the MIN to MAX completion times for all occupants, while the thick plotted line plots the range of the LOW to HIGH completion times.
Travel Distances for All Occupants (m).html
This file contains a plot of the data written to Travel Distances for All Occupants (m).csv. Double-clicking this file will open the plot, shown in Figure 5, in your default browser window. For each variation, the thin plotted line plots the range of the MIN to MAX travel distances for all occupants, while the thick plotted line plots the range of the LOW to HIGH travel distances.
path scrn mc completion times
Figure 4. Example Completion Times plot
path scrn mc travel distances
Figure 5. Example Travel Distance plot

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 distributed profile and behavior parameters (e.g. speed when entered as a uniform distribution).
--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. The initial seed is used to randomize distributed profile and behavior properties.
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.