Attractors

Reading Time: 12 minutes

Created with software version: 2023.3

1. Overview

This tutorial will demonstrate how to use Attractors in Pathfinder models. It will walk through how to create Attractors, what the different Attractor awareness types are and what they do, and how to configure the probability that an Occupant will use an Attractor that they are aware of. By the end of this tutorial, the user should be able to use Attractors in their model to roughly mimic an Occupant’s spontaneous decision making.

2. Before Starting

Before beginning this tutorial:

Download the Attractors.zip files to follow along.
Read through the Attractors section in the User Manual.

3. Introduction

Attractors are new objects introduced in Pathfinder 2021.3 that allow Occupants to mimic real-world spontaneous decision making. For example, this tutorial uses a vending machine in a waiting lobby. In this scenario, not every Occupant entering the room would interact with this vending machine. However, there may be some Occupants that are feeling hungry that moment or just want to grab a delicious snack while they wait, and decide to purchase something from the vending machine. In previous versions of Pathfinder, this behavior would most commonly be modeled via a complex chain of Behaviors and behavior changing distributions. Now with Attractors in Pathfinder 2021.3, users can simulate this behavior with a single Attractor object, an associated Behavior, and some related Profile parameters.

As stated above, the attached model simulates the scenario of a hospital waiting lobby with a set of vending machines. The Occupants in this model have one of two Profiles. Occupants with the HospitalEmployee Profile are already created at the start of the simulation, and are standing behind the counters in the hospital. Occupants with the Default Profile are created with an Occupant Source, and enter the model via the front entrance. The Occupants created by the Occupant Source are also created with the Patient Behavior, which has Occupants enter the model, enter a Queue for the front desk, interact with the front desk at a Queue Service Point, then make their way to a seating area to wait. These Occupants will wait between a range of 2 - 5 minutes, then travel further in to the hospital for between 5 - 10 minutes (represented by waiting in a back room). Some Occupants will enter a Queue for an additional consult and then enter another Queue for payment, while others will proceed directly to the payment Queue. After paying, Occupants will then exit the model.

This tutorial will demonsrate how to add an Attractor to this scenario so that at certain points in the simulation, some Occupants will decide to visit the vending machine and simulate purchasing a snack.

4. Creating an Attractor

4.1. Placing the Attractor

The first step to creating an Attractor is to first place one in the model. To place an Attractor:

Click on the Add an Attractor tool.
In the Properties Panel, select either Line of Sight or Same Room in the Awareness dropdown. (We will change this type in the next section)
Click in your model to place the Attractor.

path scrn attractor line of sight — Figure 1. A **Line of Sight** Attractor placed in the model

As you can see from Figure 1, Attractors are represented by a point in the model when using the Line of Sight or Same Room awareness types, with Line of Sight also displaying a circle representing the influence range. The other types of Attractors place in a similar manner to these two, however they do not have a visual representation in the model (unless using the <Wait at Attractor> behavior, covered in a later section).

4.2. Setting the Attractor Awareness

This section will cover the different Attractor awarenesses, what they mean in practice, and how to use them in a model. After placing an Attractor, the next step is to define the Attractor Awareness, which controls the conditions in which an Occupant will be made aware that an Attractor exists.

To define the Awareness type:

In the Navigation View, select the Attractor that was just placed.
In the Properties Panel, click the Awareness dropdown.

There are 4 Awareness types available in this dropdown. Section 9.5 of the Pathfinder User Manual covers all of the Attractor properties and the Awareness types more in depth, but in practice the different Awareness types are useful in the following situations:

Line of Sight: Useful when only Occupants within a certain radii of an Attractor should be affected by the Attractor
Same Room: Useful when only Occupants in the same room as the Attractor should be affected by the Attractor
Specified Rooms: Useful when only Occupant in certain rooms should be affected by the Attractor
Global: Useful when all Occupants should be affected by the Attractor (See Section 9.5 of the Pathfinder User Manual for an important note on this selection)

For the purpose of this tutorial, Occupants should only be affected by our vending machine Attractor when they are in specific rooms. To define this:

In the Awareness dropdown, select Specified Rooms.
Click the Rooms hyperlink to open the Rooms Selection Dialog.
In the Selection Dialog, click the checkbox next to the Main room, then the checkbox next to Show group labels
In the searchbox of the Selection Dialog, search for "Seats". This should show all of the rooms belonging to the Seats group in the model.
Click the checkbox at the top of the list to select all of the rooms in the Seats group.
Check the box next to Display only selected rows to see the entire selection. There should be 25 rooms selected in the model.
Click OK.

path scrn attractor tutorial selection dialog — Figure 2. Selected rooms for the Attractor

This will limit our Attractor to only affect Occupants that are in the waiting lobby, or that are in the rooms representing the individual waiting chairs in the lobby. Now, any Occupants in these rooms will be aware of the Attractor.

4.3. Setting the Attractor Behavior

Occupants are now aware of the Attractor, but what Behavior should they perform when they interact with the Attractor?

At the moment, this Attractor should have the default <Wait at Attractor> Behavior. This behavior is very simple. When interacting with the Attractor, Occupants will go within the Wait Area Radius location of the Attractor (represented by a point in the model), and wait for the Wait Time before continuing their prior Behavior.

This behavior is good for some scenarios, but in others, as in this tutorial, a more complex behavior is needed. Thankfully, any Behavior that can be created in Pathfinder can be the target of an Attractor, such as the GoTo Vending Behavior in this model. To assign this Behavior to the Attractor:

Select the Attractor in the Navigation View.
In the Behavior dropdown, select the GoTo Vending Behavior

path scrn attractors behaviors — Figure 3. All Behaviors that may be used by the Default profile after setting the Attractor Behavior

That’s it! Now, any Occupant that interacts with the Attractor will now perform the GoTo Vending Behavior. This is a relatively simple Behavior that sends Occupants to one of a few specific Rooms, has them wait for a few seconds, then has them resume their prior Behavior. Figure 3 this Behavior and all other behaviors that may now be used by an Occupant with the Default Profile.

4.4. Setting the Attractor Probability

The Attractor is almost fully defined. We have created the Attractor, limited Occupants' awareness of it to specific Rooms, and defined the Behavior that Occupants should use when interacting with it. But how often should Occupants interact with the Attractor when they are aware of it? This is called Attractor probability and is controlled by two sets of parameters in Pathfinder.

4.4.1. Attractor Influence

The first parameter that controls Attractor probability is the Attractor Influence. Attractor Influence controls how influential an Attractor is, the higher the influence; the higher the probability of use (given the same level of Occupant Susceptibility to Attractors.) Sticking with the vending machine example, a vending machine that is full of everyone’s favorite snacks would be a high-influence Attractor, while a vending machine that is almost empty and only has the snacks nobody likes would be a low-influence Attractor.

To view the Attractor Influence for the Attractor in this model:

Select the Attractor in the Navigation View

Attractor Influence should now be visible in the Properies Panel. Section 9.5 of the Pathfinder User Manual covers this parameter in more detail, but an important note is that while the Attractor Influence is represented as a percentage, it does not have a max value of 100%. Attractor Influence can be set above 100% to easily make an Attractor more attractive than all Attractors with the default 100%. In a similar manner, this value can be set to 0% to effectively disable the Attractor.

In this model, leave the Attractor Influence at the default 100%.

4.4.2. Occupant Susceptibility

The second set of parameters that control Attractor probability are an Occupant’s Attractor Susceptibility parameters. These parameters are located in the Movement tab of the Edit Profiles dialog. To view these parameters in this model:

In the Navigation View, double-click the Default profile.
In the Edit Profiles dialog, click the Movement tab.

The Attractor Susceptibility parameters are located at the bottom of this tab.

path ui dialog attractors edit profiles — Figure 4. The Attractor Susceptibility parameters located in the Edit Profiles dialog

4.4.2.1. Allowed Attractors

The simplest of the parameters is the Allowed Attractors parameter. This controls whether an Occupant using this profile is allowed to interact with Attractors at all. The 3 choices for Allowed Attractors are:

All: The Occupant will be able to interact with all Attractors it is aware of.
None: The Occupant will not interact with any Attractors in the model.
From List: The Occupant will only interact with Attractors that it is aware of that are in the approved list.

For this tutorial, leave Allowed Attractors set to All.

4.4.2.2. Attractor Susceptibility (Waiting)

The Attractor Susceptibility (Waiting) parameter controls how susceptible an Occupant is to Attractors while they are performing the wait action. Unlike the Attractor Influence parameter, this parameter must remain between 0% and 100%. To set this parameter:

In the Navigation View, double-click the Default profile.
In the Edit Profiles dialog, click the Movement tab.
Select constant in the Attractor Susceptibility (Waiting) dropdown, and enter 50% in the corresponding field.

When an Occupant is waiting and is aware of an Attractor, the probability that the Occupant will use the Attractor is given by multiplying the Attractor Influence and the Attractor Susceptibility (Waiting) parameters. In this example, Occupants with the Default profile that are performing the wait action will have a 50% chance of interacting with the Attractor when they are aware of it. This is given by multiplying the 100% (1.00) Attractor Influence by the 50% (0.5) Attractor Susceptibility (Waiting) to yield the Attractor Probability (Waiting) of 50% (0.5)

4.4.2.3. Attractor Susceptibility (Seeking)

The Attractor Susceptibility (Seeking) parameter is very similar to the Attractor Susceptibility (Waiting) parameter. The only difference is that this parameter only applies to non-wait actions. To set this parameter:

In the Navigation View, double-click the Default profile.
In the Edit Profiles dialog, click the Movement tab.
Select constant in the Attractor Susceptibility (Seeking) dropdown, and enter 1% in the corresponding field.

The math for this parameter is the same as for the Attractor Susceptibility (Waiting) parameter. Now, an Occupant with this profile, that is performing a non-wait action, that is also aware of the Attractor will have a 1% (1% * 100%) probability of interacting with the Attractor.

4.5. Running the Simulation

Now the Attractor is fully defined! Click the Run Simulation icon to run the simulation.

5. Results

With the simulation completed, it is now time to go over the Attractor specific Results data that is generated by Pathfinder.

5.1. The 3D view

The first thing to do is to verify that Occupants are using the Attractor as intended. This can be done by observing the model in the 3D view. To do this:

In the Pathfinder interface, click Show Results icon to open the Results Viewer.

path results attractors movie — Figure 5. An Occupant (highlighted) enters the model, goes to the counter, waits in the lobby, then interacts with the vending machine Attractor

Figure 5 shows that the Occupants do in fact interact with the Attractor, and further study of the Results show that the Occupants primarily do this only when they are performing the wait action in the lobby rooms.

5.2. Attractors in the Summary Report

The Summary Report file contains information about the simulation geometry, simulation performance, statistics, and usage infromation for each room, stairway, and door. You can read more about the Summary Report in Section 14.1 of the Pathfinder User Manual. With the addition of Attractors, this file also now includes information about Attractor Usage Time. To view this information:

Open the Attractors_summary.txt file
Find the Attractor Usage Times section

path results attractors summary — Figure 6. That Attractor Usage Times section of the Summary Report

This section lists all Attractors present in the model. Each entry lists the Attractor’s usage count, minimum usage time (with related Occupant), maximum usage time (with related Occupant), and average usage time (with standard deviation). There are also two additional entries titled no attractors and all attractors. The no attractors entry lists data for any Occupants that did not use any Attractors, and the all atractors entry lists data that summarizes the use of all Attractors in the model.

5.3. Attractors in the Occupant Summary file

The Occupant Summary file provides statistics about each Occupant in the simulation. You can read more about the Occupant Summary file in Section 14.7 of the Pathfinder User Manual. With the addition of Attractors, two additional columns are added to this file. To view this data:

Open the Attractors_Occupant.csv file
Find the num attractors used and attractor time(s) columns

path results attractors occupants data — Figure 7. Screenshot of the Attractors_Occupants.csv file, showing the **num attractors used** and **attractor time(s)** columns (highlighted).

Figure 7 shows the new num attractors used and attractor time(s) columns. The num attractors used column lists the number of Attractors that an Occupant used during the simulation, and the attractors time(s) lists the total amount of time that the Occupant spent performing and Attractor behavior.

5.4. The Attractor History file

With the addition of Attractors, a new Attractor History file was added to the Pathfinder output. This file lists the usage of Attractors over time. Each column (except the Time column) represents a single Attractor in the model. The data in each row represent the number of people using the Attractor at the given time step. You can read more about the Attractor History file in Section 14.10 of the Pathfinder User Manual.

To view this file:

Open the Attractors_attractors.csv file

path results attractors history — Figure 8. Screenshot of the Attractors_attractors.csv file, showing the usage of Attractors over time.

6. Conclusion

Users should now know how to create Attractors, should understand the different Attractor awareness types are and what they do, should understand how to configure the probability that an Occupant will use an Attractor, and how to view the new Results created by the Attractors.

To download the most recent version of Pathfinder, 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.

Attractors

Related Tutorials