With the inifile the simulation with jpscore can be controlled.

The typical structure of an inifile is as follows:

<jupedsim>
  <header>
      <!-- seed , geometry, output format, etc. -->
  </header>

  <train_constraints>
      <!-- only for simulations with tracks and trains -->
  </train_constraints>	
	
  <traffic_constraints>
      <!-- traffic information: e.g closed doors or smoked rooms -->
  </traffic_constraints>
  
  <routing>
      <goals>
	  <goal>
              <!-- goals (closed polygons) outside the geometry -->
	  </goal>
          <waiting_area>
	      <!-- goals (closed polygons) inside the geometry -->
          </waiting_area>
      </goals>
  </routing>	  

  <agents>
      <agents_distribution>
          <!-- persons information and distribution -->
      </agents_distribution>
      <agents_sources>
          <!-- sources information and distribution -->
      </agents_sources>
  </agents>

  <operational_models>
      <model id="n" description="name">
          <!-- parameters of model (<n>, "name") -->
      </model>
      <!-- other models can be defined -->
  </operational_models>

  <route_choice_models>
      <router router_id="n" description="name">
          <!-- parameters of router (<n>, "name") -->
      </router>
      <!-- other routers can be defined -->
  </route_choice_models>

</JuPedSim>

The header comprises the following elements:

  • <seed>s</seed>

    Set the seed value of the random number generator to s. If 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)

  • <logfile>log</logfile> save relevant information about the simulation to a log file with txt format. Useful to keep track of warnings or errors that may rise during a simulation.

  • <progressbar/>: show a progress bar of the simulation.

  • The trajectory file

 <trajectories format="xml-plain" fps="8" color_mode="velocity">
    <file location="trajectories.xml" />   
 </trajectories>

The options for the format are

  • xml-plain: the default xml format. It can lead to large files. See section xml-plain.

  • plain: simple text format. See section plain.
    • 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>
      

      WARNING: Files may become significantly larger!

  • The value fps defines the frame rate per second for the trajectories.

    • color_mode: coloring agents in the trajectories. Options are:
      • velocity (default): color is proportional to speed (slow –> red).
      • spotlight
      • group: color by group
      • knowledge
      • router
      • final_goal
      • intermediate_goal
    • file location defines the location of the trajectories. All paths are relative to the location of the project file.

Train constraints

Interface to trains is documented here.

Traffic constraints

This section defines constraints related to the traffic. At the moment the state of the doors can be changed (open or close)

 <traffic_constraints>
    <!-- doors states are: close or open -->
    <doors>
        <door trans_id="4" caption="Main-gate" state="open" />
        <door trans_id="6" caption="Rear-gate" state="close" />
        <door trans_id="0" caption="NaN" state="open" dn="10" outflow="2" max_agents="200"/>
        <file>traffic.xml</file>
    </doors>
 </traffic_constraints>
  • trans_id: unique id of that specific door as defined in the geometry file. See geometry.

  • caption: optional parameter defining the caption of the door.

  • state defines the state of the door. Options are close or open. Door’s properties:
  • dn: number of agents to pass the door before triggering the process of flow regulation.
  • outflow: Max flow through door. Door’s state will be changed adequately.
  • max_agents: Max agents that can pass door. Door will be closed permanently
  • file (optional) file containing further constraints. See traffic.xml

Routing

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>

Goals

Additional goals, which are defined outside the geometry. They should NOT overlap with any walls or be inside rooms. 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.
  • file file containing further goals. See goals.xml

Waiting Area

Addional goals, which are defined inside the geometry. When the waiting area is reached, pedestrians may wait till they move to one of the specified next goal (decided individually for each ped). Waiting either depends on time or till a specific door opens. They should NOT overlap with any walls or be outside rooms.

  • Waiting areas are defined with close 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 global_timer = false)
  • max_peds: the max number of pedestrians allowed inside the waiting area. Important: to avoid undefined behaviour max_peds should not exceed the number of pedestrians heading for an other waiting area. Hence max_peds(WA1) <= max_peds(WA2).
  • 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
  • global_timer: If true timer starts with start of the simulation, else timer starts when min_peds pedestrians are inside waiting area
  • transition_id: waits till the specific door opens. Important:waiting_time is neglected in this case!

  • next_wa: Next waiting area or goal where pedestrians are heading for
    • id: ID of next waiting area/goal
    • p: probability of pedestrians being led to the specific next waiting area. During simulation if max_ped of the particular waiting is reached it will not be considered.

Agents

There are two ways to distribute agents for a 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>

Agents_distribution

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 -1 then the shortest exit to the outside is chosen by the agent.

  • router_id: defines the route choice model to be used. See documentation of available routers.

  • agent_parameter_id: choose a set of parameters for the operational models.

  • x_min, x_max, y_min and y_max: define a bounding box where agents should be distributed.

  • startX, startY: define the initial coordinate of the agents. This might be useful for testing/debugging. Note that these two options are only considered if number=1.

  • pre_movement_mean and 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 :

    • risk_tolerance_mean and risk_tolerance_sigma: .

    • risk_tolerance_alpha and risk_tolerance_beta: .

  • 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 the operational models.

  • gender: not yet used.

  • height: not yet used.

Sources

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 are as follows.

  • id: id of the source
  • caption: caption
  • frequency: time in seconds of generation of pedestrians (default = 1).
  • N_create: How many agents to create at once (default = 1).
  • percent: percent of N_create to generate (default = 1).
  • rate: rate of generation of agents (in seconds).
  • time_min, time_max: Time lifespan of the source.
  • agents_max: maximal number of agents produced by that source.
  • group_id: group id of the agents. This id should match a predefined group in the section Agents_distribution.
  • time: time of appearance of agent with id agent_id. Here agents_max=1.
  • startX, startY: Distribute one agent at a fix position.
  • x_min, x_max, y_min, y_max: Bounding box for generation of agents.
  • greedy (default false): returns a Voronoi vertex randomly with respect to weights proportional to squared distances. For vertexes and distances to their surrounding seeds calculate the probabilities as

    If this attribute is set to true, the greedy approach is used. That means new agents will be placed on the vertex with the biggest distance to the surrounding seeds.

  • file: a file containing further sources. See sources.xml

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"  greedy="true"/>

Operational models

One of the available operational models should be defined.

Router

One of the available routers should be defined.