The header comprises the following elements:
seedvalue of the random number generator to
s. If the tag is empty or missing, the current time (
time(NULL)) is used i.e. random initial conditions.
<max_sim_time>t</max_sim_time>the maximal simulation time in seconds.
<num_threads>n</num_threads>the number of used cores.
<geometry>geometry.xml</geometry>The name and location of the geometry file. All file locations are relative to the actual location of the project file. See specification of the geometry format.
<events_file>events.xml</events_file>The name and location of the event file. Events can be used to open or close doors at a certain point of time. See event_file.
<schedule_file>schedule.xml</schedule_file>The name and location of the schedule file. Schedules can be used to group doors and open or close this groups of door at certain points of time. See schedule_file
<show_statistics>true</show_statistics>Show different aggregate statistics e.g. the usage of the doors. (default: false)
<output path="output_directory" />The name and location where the results of the simulation should be stored. The program creates a folder with the given name and copies all needed files of the simulation to this folder. Additionally the file names in the ini and geometry file are updated. Resulting in a folder with the results and everything to reproduce a specific simulation. If no output path is given the folder is named
The trajectory file
<trajectories format="plain" fps="8" precision="2" color_mode="velocity"> <file location="trajectories.txt" /> </trajectories>
The options for the format are
plain: simple text format. See section plain.
fps: defines the frame rate per second for the trajectories.
precision: define the precision of the trajectories’ points. Value can be between 1 and 6. (default: 2).
color_mode: coloring agents in the trajectories. Options are:
velocity(default): color is proportional to speed (slow –> red).
group: color by group
file locationdefines the location of the trajectories. All paths are relative to the location of the project file.
optional_output: possibility to give additional output. Set any of these values to
TRUE(not case sensitive) to get the according value.
FALSE, any other value and ignoring the option will lead to no output. -
speed: speed of the pedestrian -
velocity: x,y components of the pedestrians’s velocity -
final_goal: id of the final goal the pedestrian is heading to -
intermediate_goal: id of the current goal the pedestrian is heading to (usually a door) -
desired_direction: x,y components of the pedestrians’s desired directions -
group: group of the pedestrian -
router: router used by the pedestrian (id accoriding to ini-file) -
spotlight: pedestrian is highlighted.
<trajectories format="plain" fps="8"> <file location="bottleneck_traj.txt" /> <optional_output speed="FALSE" velocity="TRUE" final_goal="NoOutputWrongValue" intermediate_goal="false" desired_direction="true" group="TRUE" router="TRUE" spotlight="TRUE"/> </trajectories>
In the inifile the following section should be defined, where two files are specified:
<train_constraints> <train_time_table>ttt.xml</train_time_table> <train_types>train_types.xml</train_types> </train_constraints>
For detailed information see here.
This section defines constraints related to doors.
<traffic_constraints> <doors> <file>traffic.xml</file> </doors> </traffic_constraints>
filefile containing further constraints. See traffic.xml
The routing comprises additional goals, which might be defined inside or outside the geometry.
<routing> <goals> <goal id="0" final="false" caption="goal 1"> <polygon> <vertex px="-5.0" py="-5.0" /> <vertex px="-5.0" py="-2.0" /> <vertex px="-3.0" py="-2.0" /> <vertex px="-3.0" py="-5.0" /> <vertex px="-5.0" py="-5.0" /> </polygon> </goal> <waiting_area caption="wa1" id="1" waiting_time="20" min_peds="5" max_peds="10" is_open="true" room_id="0" subroom_id="1" global_timer="false" transition_id="1"> <polygon> <vertex px="11" py="1" /> <vertex px="14" py="1" /> <vertex px="14" py="4" /> <vertex px="11" py="4" /> <vertex px="11" py="1" /> </polygon> <next_wa id="2" p="0.75"/> <next_wa id="3" p="0.25"/> </waiting_area> <file>goals.xml</file> </goals> </routing>
Additional goals, which are defined outside the geometry.
It is recommended to position them near the exits.
- Goals are defined with close polygons, with the last vertex is equal to the first one.
filefile containing further goals. See goals.xml
Addional goals, which are defined inside the geometry.
Here are some use cases:
- Waiting: Designated waiting areas where pedestrians wait for a specific time or till an specific door opens. After waiting is over the move to one of the specified next goal (decided individually for each ped).
- Manual routing: Goals which should be passed before leaving the building without waiting (
waiting_time="0"). Can be used to reduce jam in front of bottlenecks or ensuring pedestrian walk through certain paths.
Waiting areas are defined as closed polygons, with the last vertex is equal to the first one.
file: file containing further goals/waiting areas. See goals.xml
waiting_time: the time pedestrians wait inside the waiting area
min_peds: the number of pedestrians needed in the waiting area to start the timer (if
max_peds: the max number of pedestrians allowed inside the waiting area.
max_pedsshould not exceed the number of pedestrians heading for an other waiting area. Hence
is_open: defines whether the waiting area is open for pedestrians
room_id: ID of room containg waiting area
subroom_id: ID of subroom containing waiting area
truetimer starts with start of the simulation, else timer starts when
min_pedspedestrians are inside waiting area
transition_id: waits till the specific door opens. Important:
waiting_timeis neglected in this case!
next_wa: Next waiting area or goal where pedestrians are heading for
id: ID of next waiting area/goal, -1 for next exit
p: probability of pedestrians being led to the specific next waiting area. During simulation if
max_pedof the particular waiting is reached it will not be considered.
There are two ways to distribute agents for a simulation:
- random distribution in a specific area before the simulation starts.
- distribution by means of sources during the simulation.
<agents> <agents_distribution> <group group_id="1" room_id="0" number="10" /> <group group_id="2" room_id="0" subroom_id="0" number="10" goal_id="" router_id="1" /> </agents_distribution> <agents_sources> <source id="1" frequency="2" agents_max="10" group_id="1" caption="caption" greedy="true"/> <source id="2" time="10" agent_id="50" group_id="1" caption="caption" greedy="true"/> <source id="10" caption="new-source" time_min="5" time_max="30" frequency="5" N_create="10" agents_max="300" group_id="0" x_min="0" x_max="3" y_min="0" y_max="3" percent="0.5" rate="2" greedy="true"/> <file>sources.xml</file> </agents_sources> </agents>
Above is an example how to define agent’s characteristics with different number of attributes, which are as follows:
group_id: mandatory parameter defining the unique id of that group.
number: mandatory parameter defining the number of agents to distribute.
room_id: mandatory parameter defining the room where the agents should be randomly distributed.
subroom_id: defines the id of the subroom where the agents should be distributed. If omitted then the agents are homogeneously distributed in the room.
goal_id: should be one of the
ids defined in the section goals. If omitted or is
-1then the shortest exit to the outside is chosen by the agent.
router_id: defines the route choice model to be used. See routing documentation of available routers.
agent_parameter_id: choose a set of parameters for the operational models.
y_max: define a bounding box where agents should be distributed.
startY: define the initial coordinate of the agents. This might be useful for testing/debugging. Note that these two options are only considered if
pre_movement_sigma: premovement time is Gauss-distributed .
Risk tolerance can be Gauss-distributed, or beta-distributed. If not specified then it is defined as :
patience: this parameter influences the route choice behavior when using the quickest path router. It basically defines how long a pedestrian stays in jams before attempting a rerouting.
age: not yet used by any of the operational models.
gender: not yet used.
height: not yet used.
Besides distributing agents randomly before the simulation starts, it is possible to define sources in order to “inject” new agents in the system during the simulation. The parameter of the sources defined here.
An example of usage:
- Busses are coming every 10 min (600 seconds).
- Every bus transports 100 pedestrians.
- When the bus stops, every 2 seconds 10 pedestrians leave the bus.
- 3 Buses at max.
<source id="10" frequency="600" N_create="100" agents_max="300" percent="0.1" rate="2"/>
One of the available operational models should be defined.
One of the available routers should be defined.