Quick Start: Writing Input csv file for CrowdEgress

About Simulation Model

Agent-based model (ABM) describes interactions among individual agents and their surroundings. In the simulation there are four types of entities: agents, walls, doors and exits. As below we will introduce how to specify these entities.

The walls, doors and exits are alternatively specified by FDS input files. Users are welcome to use existing FDS input files to create compartment geometries. In current version only one-floor crowd simulation is supported. So if there are multiple evacuation meshes in FDS input files, they should all belong to the same z interval in the vertical direction (z axis). By using FDS input files the walls are created by &OBST, and the doors are specified by &HOLE or &DOOR. The exits are obtained from &EXIT in FDS input files. If users want to find more about how FDS define a compartment area, please refer to FDS UserGuide for more information. If users do not use FDS input files, the above entities can alternatively be specified by using csv files as introduced below.

Walls: Walls are obstruction in a compartment geometry that confine agent movement, and they set up the boundary of a room or certain space that agents cannot go through. In our program wall are either lines or rectangular areas. If any users are interested, please feel free to extend the wall types to circular or polyangular areas. If users import walls from a FDS input file, the walls are created as a rectangular type and it corresponds to &OBST in FDS input file. If users specify a line obstruction, it is expected to input the position of starting point and ending point of a line. If users specify a rectangular obstruction, it is expected to input the diagonal position of upper left point and lower right point of a rectangular area. Just like walls in normal buildings, walls may be labeled with arrows that direct agent to move toward certain directions. In our program wall are either lines or rectangular areas. If any users are interested, please feel free to extend the wall types to circular or poly-angular areas.

<startX, startY>: Upper left point for rectangular obstruction; Or starting point for line obstruction.

<endX, endY>:Lower right point for rectangular obstruction; Or ending point for line obstruction.

|arrow|: Direction assigned to the obstruction so that agents will be guided when seeing this obstruction, especially when they do not have any target door or exit. The direction implies if the obstruction provides evacuees with any egress information such as exit signs on the walls or not. The value could be +1 for positive x direction, -1 for negative x direction, +2 for positive y direction and -2 for negative y direction. If no direction is given, the value is 0.

|id|: id number assigned to this obstruction; id number is optionally shown in the pygame screen so that users can easily modify the obstruction.

|inComp|: a boolean variable to indicate if the obstruction is in computation loop or not. Normally it is given true/1. If users want to quickly remove a obstruction in simulation, it is assigned be to false/0.

|mode|: Either rectangular or line obstruction in current program; the default mode is rectangular model.

Doors: Doors are passageways that direct agents toward certain areas, and they may be placed over a wall so that agents can get through the wall by the door. Doors can also be placed as a waypoint if not attached to any walls, and they can be considered as arrows or markers on the ground that guide agent egress movement. In brief doors affect agent way-finding activities and they help agents to form a roadmap to exits. In current program doors are only specified as rectangular object.

<startX, startY>: Upper left point for rectangular door.

<endX, endY>:Lower right point for rectangular door.

|arrow|: Direction assigned to the door so that agents will be guided when seeing this obstruction, especially when they do not have any target door or exit. The direction implies if the door provides evacuees with any egress information such as exit signs or not. The value could be +1 for positive x direction, -1 for negative x direction, +2 for positive y direction and -2 for negative y direction. If no direction is given, the value is zero. Please refer to FDS+Evac manual to better understand the direction setting.

|id|: id number assigned to this door; id number is optionally shown in the pygame screen so that users can easily modify the door.

|inComp|: a boolean variable to indicate if the door is in computation loop or not. Normally it is given true. If users want to remove a door in simulation, they could assign it be to false for a quick test.

|exitSign|: a boolean variable to indicate if the door is attached with an exit sign or not. If there is an exit sign the boolean variable is given true. Actually it is not that useful in existing door selection algorithm.

Exits: Exits are a special types of doors which represent paths to the safety. Thus they may be deemed as safety areas, and computation of an agent is complete when the agent reaches an exit. An exit is usually placed over a wall like doors, but it can also be put anywhere independently without walls. In the program exits are only defined as rectangular areas. The specific features of an exit is given as below.

<startX, startY>: Upper left point for rectangular exit.

<endX, endY>:Lower right point for rectangular exit.

|arrow|: Direction assigned to the exit so that agents will be guided. The direction implies if the exit provides evacuees with any egress information such as exit signs or not. The value could be +1 for positive x direction, -1 for negative x direction, +2 for positive y direction and -2 for negative y direction. If no direction is given, the value is zero. Actually the direction is not that useful for an exit. It does not matter if it is assigned to be zero or not because agents head to exits from all directions.

|id|: id number assigned to this exit; id number is optionally shown in the pygame screen so that users can easily modify the exit.

|inComp|: a boolean variable to indicate if the exit is in computation loop or not. Normally it is given true. If users want to remove an exit in simulation, they could assign it be to false for a quick test.

|exitSign|: a boolean variable to indicate if the exit is attached with an exit sign or not. If there is an exit sign the boolean variable is given true. Actually it is not that useful in existing exit selection algorithm.

Agents: Finally and most importantly, agents are the core entity in computation process. They interact with each other to form collective behavior of crowd. They also interact with above types of entities to form egress motion toward exits. The resulting program is essentially a multi-agent simulation of pedestrian crowd. Each agent is modeled by extending the well-known social force model. The model is further advanced by integrating several features including pre-evacuation behavior, group behavior, way-finding behavior and so forth.')

<InitalX, InitialY>: Initial position of an agent in 2D planar space.

<DestX, DestY>: Destination position in 2D planar space. This value is almost not used in current computational loop because the destination position is automatically determined by the exit selection algorithm. When the exit is selected by an agent, the destination position is given by the exit position. |mass|: The mass of agents.
|tau|: Tau parameter in the social force model, or as usually called relaxation time in many-particle systems or statistical physics, and it critically affects how fast the actual velocity converges to the desired velocity.
|tpre|: Time period for pre-evacuation stage. |interRange|: The range when agents have herding effect, which means they may exchange opinions by talking. |p|: parameter p in opinion dynamics, and it affects herding effect.
|pMode|: This parameter affects how parameter p is dynamically changing. Currently it is not used in computational loop.
|aType|: The type of way-finding behaviors. Some agents may actively search for exits while others may just follow the crowd. In current simulation all agents follow the egress flow field, and thus this parameter is not actually used in existing version of code.
|ID|: ID number assigned to this agent. ID number is optionally shown in the pygame screen. \n\n|inComp|: a boolean variable to indicate if the agent is in computation loop or not. Normally it is given true. If users want to remove an agent in simulation, they could assign it be to false for test.