docs/2016-11-01-inifile.md

+---
+layout: post
+title: Project file
+subtitle: inifile 
+cover: /img/jupedsim_small.png
+permalink: 2016-11-01-inifile.html
+---
+
+
+With the content of the `inifile`, the simulation with `jpscore` can be controlled. 
+
+The typical structure of an `inifile` is as follows:
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<JuPedSim project="JPS-Project" version="0.8"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+          xsi:noNamespaceSchemaLocation="https://github.com/JuPedSim/jpscore/blob/master/xsd/jps_ini_core.xsd">
+
+    <header> 
+         <!-- seed , geometry, output format -->
+    </header>        
+
+    <traffic_constraints> 
+        <!-- traffic information: e.g closed doors or smoked rooms -->
+    </traffic_constraints>
+
+
+    <goals>
+    <!-- goals (closed polygons) outside the geometry-->
+    </goals>
+
+
+    <agents>
+        <agents_distribution>
+            <!--persons information and distribution --> 
+        </agents_distribution>
+    </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 main components of the inifile are: 
+
+- [header](#header)
+- [traffic constraints](#traffic-constraints)
+- [goals](#goals)
+- [agents](#agents)
+- [operational models](2016-11-01-operativ.html).
+- [route choice models](2016-11-03-routing.html).
+
+***
+
+### Header
+
+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.
+
+-   `<show_statistics>true</show_statistics>` Show different aggregate statistics e.g. the usage of the doors. (default: false) 
+
+-   `<logfile>log.txt</logfile>` save relevant information about the simulation to a log file. 
+  Useful to keep track of warnings or errors that may rise during a simulation.
+
+-  The trajectory file   
+
+```bash 
+<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](2016-11-03-trajectory#xml-plain).
+
+-   `plain`: simple text format. See section [plain-text](2016-11-03-trajectory#plain-text).
+
+- 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.
+
+-   `<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](2016-11-02-geometry.html) of the geometry format.
+
+### Traffic constraints
+
+This section defines constraints related to the traffic. 
+At the moment the state of the doors can be changed (`open` or `close`)
+
+
+```xml
+<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" />
+    </doors>
+</traffic_constraints>
+```
+
+- `trans_id`: unique id of that specific door as defined in the geometry file. See [geometry](2016-11-02-geometry.html).
+
+- `caption`: optional parameter defining the caption of the door.
+
+- `state` defines the state of the door. Options are `close` or `open`.
+
+### Goals 
+
+Additional goals might be 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*.
+
+```xml
+<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>
+        <goal id="1" final="false" caption="goal 2">
+            <polygon>
+                <vertex px="15.0" py="-5.0" />
+                <vertex px="17.0" py="-5.0" />
+                <vertex px="17.0" py="-7.0" />
+                <vertex px="15.0" py="-7.0" />
+                <vertex px="15.0" py="-5.0" />
+            </polygon>
+        </goal>
+    </goals>
+</routing>
+```    
+
+
+### Agents
+
+There are two ways to distribute agents for  a simulation:
+
+- [random distribution](#agents_distribution) in a specific area *before* the simulation starts. 
+- distribution by means of [sources](#sources) *during* the simulation.
+
+#### Agents_distribution
+An example how to define agent's characteristics with different number of
+attributes is as follows
+
+```xml
+    <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" />
+                
+            <group group_id="3" room_id="0" subroom_id="1" number="20" 
+                goal_id="1" router_id="2" patience="5"/>
+                
+            <group group_id="4" room_id="0" number="200" goal_id="-1" 
+                router_id="2" patience="50"/>
+                            
+            <group group_id="5" room_id="0" number="1" startX="25.3" startY="365.90"/>
+
+        </agents_distribution>
+    </agents>
+```
+
+- `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 `id`s defined in the section  [goals](#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](2016-11-03-routing.html) of available routers.
+
+- `age`: not yet used by the [operational](2016-11-01-operativ.html) models.
+
+- `gender`: not yet used.
+
+- `height`: not yet used.
+
+- `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.
+
+- `premovement_mean` and `premovement_sigma`: premovement time is Gauss-distributed $$\mathcal{N}(\mu, \sigma^2)$$.
+
+- Risk tolerance can be Gauss-distributed, or beta-distributed. 
+  If not specified then it is defined as $$\mathcal{N}(1, 0)$$:
+
+  - `risk_tolerance_mean` and `risk_tolerance_sigma`: $$\mathcal{N}(\mu, \sigma^2)$$.
+
+  - `risk_tolerance_alpha` and `risk_tolerance_beta`: $$Beta(\alpha, \beta)$$.
+
+- `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`.
+
+- `agent_parameter_id`: choose a set of parameters for the [operational models](2016-11-01-operativ.html).
+
+#### 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.
+
+```xml
+<agents_sources>
+<source id="1" frequency="2", agents_max="10" group_id="1", caption="caption" greedy="true"/>
+</agents_sources>
+```
+
+- `id`: id of the source
+- `frequency`: number of pedestrians per second.
+- `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](#agents_distribution).
+- `caption`: caption
+- `greedy` (default `false`): returns a Voronoi vertex randomly with respect to weights proportional to squared distances.  
+   For vertexes $$v_i$$ and distances $$d_i$$ to their surrounding seeds
+   calculate the probabilities $$p_i$$ as  
+   
+   $$p_i= \frac{d_i^2}{\sum_j^n d_j^2}.$$
+   
+   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.
+