Pathfinder Scripting API Manual

1. Getting Started

Pathfinder scripts can be edited within the Pathfinder user interface and are stored with other model data inside the save file (PTH). Once a script has been added to a model, it will automatically be used any time anyone runs that model.

Since this is an experimental feature, a flag must be set to enable the script editor. This flag can be set by either running Pathfinder from a console window (recommended when creating/debugging scripts) or by editing the Windows Start Menu shortcuts.

To enable the script editor, it is necessary to add the following VM argument when running Pathfinder:

-Dex_enable_scripting

The above form of the argument can be used as-in when part of a batch file (e.g. monte carlo runs), but requires a modification when running Pathfinder as part of a shortcut or from the command line:

-J-Dex_enable_scripting

The -J instructs the wrapper executable to unpack the argument as a VM parameter.

For example:

pathfinder.exe -J-Dex_enable_scripting

Once this flag has been enabled, an option will be added to the Model : Model › Edit Custom Scripts menu If the script editor is not enabled, the presence of custom scripts will trigger a warning when loading the PTH file.

When working with scripts, please keep in mind the following details:

2. Introduction

The Pathfinder API provides low-level access to the internals of a Pathfinder simulation.

It consists of four modules:

The v1 on the end of the object name gives access to a specific version of that API and will allow us to keep legacy scripts operational if we introduce API-breaking changes.

The following convenience variables will be used in all examples in this documentation.

var sim = api.simctl.v1;
var geom = api.geometry.v1;
var agents = api.agents.v1;
var io = api.io.v1;

3. Core API

The Core API describes operations that are explicitly supported by Pathfinder’s API.

var sim = api.simctl.v1;

sim.onUpdate( function (t) {

   // do this every time step

});

sim.onExit( function () {

   // do this once after the simulation has ended
   // recommended for closing PrintStream

});

var geom = api.geometry.v1;

var door = geom.find("Door to Atrium");

var doors = geom.findAll("Door to Atrium");

geom.close( door );

geom.open( door );

//Set the door direction to allow travel in both directions.
geom.setDoorDir( door, "" );
//Set the door direction closest to the +X axis.
geom.setDoorDir( door, "+x" );
//Set the door direction closest to the vector (1, -.2)
geom.setDoorDir( door, "1 -.2" );

var agents = api.agents.v1;

var agent = agents.find("00028");

var regionA = geom.find("Region-A");
var agentsInRegionA = agents.findAll( regionA );

var agentsNamedStaff = agents.findAll( "staff-??" );

var agents = agents.getAllAgentsEver();

var io = api.io.v1;

var fileout = openPrintStream("myfile.tsv");

io.out.println("message");

io.err.println("message");

(TBD)

4. Extended API

The Core API describes operations that are explicitly supported by Pathfinder’s API, but it’s possible to access a much wider range of objects. An example of a common situation is when dealing with the findAll() methods that return an instance of java.util.List. Another example is the OccAgent object that is returned by the find() method. In addition, you can create arbitrary instances of objects using the API.

In general:

Create a file using the Java platform library.

var PSType = Java.type("java.io.PrintStream");
var fileStream = new PSType("myfile.txt");

fileStream.println("Hello");

filestream.close();

Basically, you can write any program you want by using the extended API because it encompasses both JavaScript and the Java platform. The details of how to really dive into these is beyond the scope of this document, but if you have specific questions or requests for code examples, please send us an email.

5. Examples

The following examples combine elements of the script API.

var sim = api.simctl.v1;
var geom = api.geometry.v1;

var door = geom.find("Station Entrance");

sim.onUpdate( function (t) {

	var tc = t % 40.0;
	if (tc < 30) {
		geom.close(door);
	}
	else
	{
		geom.open(door);
	}
});

var sim = api.simctl.v1;
var geom = api.geometry.v1;
var agents = api.agents.v1;

var rA = geom.find("Region A");
var doorToA = geom.find("Door to Zone A");

var rB = geom.find("Region B");
var doorToB = geom.find("Door to Crossroad");

sim.onUpdate( function (t) {

	var agentsInRegionA = agents.findAll(rA);
	if (agentsInRegionA.size() > 100)
	{
		geom.close(doorToA);
	}
	else
	{
		geom.open(doorToA);
	}

	var agentsInRegionB = agents.findAll(rB);
	if (agentsInRegionB.size() > 100)
	{
		geom.close(doorToB);
	}
	else
	{
		geom.open(doorToB);
	}
});

var sim = api.simctl.v1;
var geom = api.geometry.v1;
var agents = api.agents.v1;
var io = api.io.v1;

var rA = geom.find("Region A");
var rB = geom.find("Region B");

var dtOutput = 10.0;
var nextOutput = 0.0;

// header
io.out.println("Time\tA\tB");

sim.onUpdate( function (t) {

  if (nextOutput <= t)
  {
    var nA = agents.findAll(rA).size();
    var nB = agents.findAll(rB).size();

    // data rows
    io.out.println(t +"\t" + nA +"\t" + nB);

    nextOutput += dtOutput;
  }

});