Vadere: An open-source simulation framework to promote interdisciplinary understanding

TL;DR

Vadere is an open-source pedestrian simulation framework designed to facilitate interdisciplinary research by providing a lightweight, user-friendly platform with multiple models for comparing crowd dynamics approaches.

Contribution

It introduces a versatile, open-source simulation tool that consolidates various pedestrian models, enabling cross-disciplinary understanding and comparison.

Findings

Provides pre-implemented widely used models

Enables comparison of different crowd dynamics approaches

Supports interdisciplinary research and development

Abstract

Pedestrian dynamics is an interdisciplinary field of research. Psychologists, sociologists, traffic engineers, physicists, mathematicians and computer scientists all strive to understand the dynamics of a moving crowd. In principle, computer simulations offer means to further this understanding. Yet, unlike for many classic dynamical systems in physics, there is no universally accepted locomotion model for crowd dynamics. On the contrary, a multitude of approaches, with very different characteristics, compete. Often only the experts in one special model type are able to assess the consequences these characteristics have on a simulation study. Therefore, scientists from all disciplines who wish to use simulations to analyze pedestrian dynamics need a tool to compare competing approaches. Developers, too, would profit from an easy way to get insight into an alternative modeling ansatz. Vadere meets this interdisciplinary demand by offering an open-source simulation framework that is lightweight in its approach and in its user interface while offering pre-implemented versions of the most widely spread models.

Tables

Table 1. TABLE I: Open-source simulation frameworks for pedestrian dynamics (in alphabetical order).

Simulator Name	Released	Language	Files	LoC
FDS+Evac [46]	2007	Fortran	715	249,702
JuPedSim [10]	2014	C++	774	173,973
Menge [12]	2014	C++	697	67,476
MomenTUMv2 [43]	2016	Java	814	56,569
SUMO [50]	2001	C++	1,618	253,472
Vadere	2010	Java	977	73,145

Table 2. TABLE II: Software requirements for Vadere (taken from [ 64 , p. 17] )

Functional:	- run simulations of pedestrian crowd behavior - specify and store parameters in text files with a simple format - online processing of the simulation - online and post-visualization - integrated graphical user interface
Non-functional :	- only use open-source software - run on modern desktop hardware - platform independence - object-oriented, high-level programming language - implement new models without changing the framework - framework must not impose any model concept or structure - modular design and architecture - re-usability of basic algorithms and data structures

Equations

$$\begin{array}{rl}||\nabla u(x)||f(x)& =1\text{mbox}forx\in \Omega \subset {\mathbb{R}}^2\\ u(x)& =0\text{mbox}ifx\in \Gamma .\end{array}$$

$$F_l^t=\frac{1}{{\tau }_l}\left(v_l^0{e}_l-{\dot{x}}_l\right).$$

$$\dot{w_l}=F_l+fluctuation,$$

$${\dot{x}}_l=v_l(w_l)=\{\begin{array}{ll}{w}_l& \text{if }||w_l||\le v_l^{max}\\ w_l\frac{v_l^{max}}{||w_l||}& \text{otherwise}.\end{array}$$

$$e_l=\frac{-\nabla u(x_l)}{||\nabla u(x_l)||},$$

$$s_l^0={\beta }_0+{\beta }_1\cdot v_l^0+ϵ,{\beta }_0,{\beta }_1>0,ϵ\sim \mathcal{N}(0,{\sigma }^2),$$

$$P_l(x)$$

$$P_{p,l}(x)$$

$$P_o(x)$$

$$P_{p,l,i}(x)=\{\begin{array}{ll}{P}_{p,l,i}^{\text{tor}}(x)& \text{if }{d}_i(x)<r_i+r_l\\ P_{p,l,i}^{\text{int}}(x)& \text{if }{r}_i+r_l\le d_i(x)<{\delta }_l^{\text{int}}\\ P_{p,l,i}^{\text{per}}(x)& \text{if }{\delta }_l^{\text{int}}\le d_i(x)<{\delta }_l^{\text{per}}\\ 0& \text{else}.\end{array}$$

$$P_{p,l,i}^{\text{tor}}(x)$$

$$P_{p,l,i}^{\text{int}}(x)$$

$$P_{p,l,i}^{\text{per}}(x)$$

$$d_i(x)=||y_i-x||.$$

$$x_{k+1}=\underset{y\in \mathrm{disc}(x_k)}{\mathrm{argmin}}{P}_l(y)$$

$$\mathrm{disc}(x_k)=\{y\in {\mathbb{R}}^2:\Vert y-x_k\Vert \le s_l^0\}.$$

Full text

I Introduction

Pedestrian dynamics is an active and versatile research area that attracts scientists from sociology and psychology to engineering, computer science and mathematics. This interdisciplinary scientific community shares a common goal: to enhance the understanding of crowd behavior. Scientists approach this goal from different angles: For example, sociologists and psychologists observe and analyze the human behaviors that affect pedestrian movement [17]. They describe their findings verbally. Mathematicians and physicists mold the observed behavior into equations [34]. Computer scientists develop computer models based on these equations [64]. Each researcher wants to get new insights by using different but connected techniques and by asking different but connected questions.

The interdisciplinary character of pedestrian dynamics entails communication problems and misunderstandings: For example, the term “agent” [2] used by computer scientists to denote a simulated pedestrian may not be immediately understood as such by psychologists. The term “crowd” has a very rich meaning for social psychologists [61, 16, 6] while a physicist may simply think of an aggregation of individuals like an aggregation of particles [71]. A third prominent example is the term “panic”. While panic is considered as myth by sociologist and human behaviour scientists [19], this word is still used by many computer scientists [33, 35]. Thus terms might even be misleading in an interdisciplinary group. The consequences of these language difficulties go beyond research as soon as decision makers at crowded events, such as city planners and the police apply research results.

A pedestrian simulation tool reflects the interdisciplinary character of the field. Behaviors that were observed and described by empirical scientists are operationalized, then mapped to equations, algorithms, and finally computer programs. These computer programs can be executed to reenact real scenarios in a virtual world, where they can be re-observed. Therefore, they are a powerful tool to foster interdisciplinary understanding in pedestrian dynamics.

Laboratory and field experiments are essential to understand pedestrian behavior, but they need participants and bind a lot of scientific and non-scientific human resources. Here simulations can help out [29, 28]. Also, they are generally more time-efficient. Generating data such as trajectories is easy and often fully automated, while to this day, extracting trajectories from video footage remains a semi-manual process. Parameter variation is straight forward while it is costly and time-consuming in controlled experiments and impossible in field observations. Aside from practical and economic considerations, simulations can address situations that would be unethical in an experiment, e. g. situations with dangerously high densities. Beside simulations, virtual and augmented reality environments offer possibilities to test such critical scenarios without endangering probands [44, 21, 53].

In addition, scientists can learn from studying the model, that is, the set of equations itself, provided the model matches reality sufficiently well. Whether a match is good or not depends on the particular research question.

At this point, researchers are faced with a challenge: the vast number of competing models from which they can choose [82, 34, 3, 68]. Pedestrian dynamics deal with the most sophisticated organism on earth, the human being. At the same time, the field is relatively new, with most of the progress and publications stemming from this millennium as illustrated by the search result shown in Fig. 1. Therefore, it is not surprising that there is no universally accepted model of pedestrian dynamics. Indeed, the number of models and the level of detail they try to map is still growing.

One way to categorize pedestrian simulation models is by their scale: macroscopic and microscopic [57]. For both categories, the goal is to reproduce coarse-scaled quantities like densities (measured in persons per area) or flow (measured in persons per second). While macroscopic models, such as [38, 74], see the crowd as a continuum, microscopic models see it as an aggregate of individuals. Consequently, individuals are simulated based on their distinct attributes, such as their desired speeds. In addition to coarse-scaled quantities, fine-scaled quantities like the velocity or step length of a pedestrian at a certain time can be measured. Therefore, fine-scaled phenomena observed in the real world, such as the decrease in step length with increasing density, can be reproduced as well.

Microscopic models are often conceptually divided into three levels: (1) the strategic level: activity choice, (2) the tactical level: activity schedule, area and route choice to reach the area and (3) the operational level: walking behavior. A description can be found in [37]. The operational level, that is, the walking behavior, is embodied by a specific locomotion model. In this contribution, we focus on the locomotion level. We argue that walking behavior must be modeled adequately before we can move on to modeling more complex situations, that is, before we can build a tactical and strategic level on top. Several approaches for modeling microscopic pedestrian dynamics have been developed in the last decades [88]. Among these are models based on cellular automata (CA) [25, 5, 45, 79, 18, 87], models based on ordinary differential equations (ODE) [34, 9, 8, 14, 73], models based on cognitive heuristics [65, 84] and models based on optimizing a utility, such as the quasi-continuous optimal steps model [68, 75, 76, 77].

In short, even on the locomotion level alone, practitioners and researchers can pick and choose from a rich selection of solution proposals that may or may not be suitable for their research question. For example, in a large and open field scenario with millions of pedestrians a fast cellular automaton model may be a good, and perhaps the only choice, to gain first insights, while it will fail in situations with fine granularity. It is very difficult to make decisions on model descriptions alone.

This is where we introduce Vadere. It is a free and open-source pedestrian simulation framework for microscopic pedestrian dynamics that was expressively conceived to facilitate comparison between locomotion models. Thus, it comes with pre-implemented versions of the most widely spread locomotion models. Vadere is released under the LGPL license.

Alternative implementations of the above-mentioned models are offered by a large number of commercial simulators, like PTV (social force model), LEGION (unknown model) and accu:rate (optimal steps model). However, to understand the dynamics of a simulation, not only the mathematical formulation of the model but also its implementation must be known and well understood. Indeed, the mathematical description will often differ from its implementation [10]. For example, the mathematical model definition might be through an ordinary differential equation (ODE) as in force based models. The algorithmic formulation, on the other hand, is through a numerical solver, such as Euler’s method, which may – or may not – converge to the solution of the ODE. See [47] for numerical issues. Another example is the use of different pseudo random number generators with different starting seeds. We assume a world of irrational numbers and true random numbers which do not exist in the coding world. Those details are often not mentioned in the model description. Thus, easy access to the code is a key requirement.

Several other open-source pedestrian dynamics simulators exist, for example FDS+Evac [20], JuPedSim [10], Menge [12], MomenTUMv2 [42] and SUMO [70]. All frameworks share common conceptual characteristics but differ in their goals. Vadere is a lightweight simulator. The framework focuses on comparing existing and implementing new locomotion models and, at this point, solely covers the operational level, to keep the core simple and expandable. Developers can focus only on the model code, the rest is offered by the common code base. As a consequence, Vadere offers modern algorithms and data structures, and many more tools like a graphical user interface (GUI), Python scripts to compare simulation outputs and a command line interface to run multiple simulations in a systematic manner. All those features support and simplify the scientific work, especially the calibration and validation of locomotion models whose importance is emphasized in [10]. In the spirit of interdisciplinary collaboration, the secondary focus of Vadere is its usability, which we continuously improve. The open-source approach allows other researchers to use and extend Vadere to their needs.

In Section II, we give an overview on existing locomotion models and pedestrian dynamics simulators that implement subsets of these models. In Section III, we introduce the Vadere simulation framework. We show core features of Vadere which are relevant for users. Moreover, we reveal technical details which are essential when implementing a generic software framework that supports multiple locomotion models. In addition, we shed light on how we test our simulation software while it is being improved and used continuously.

II Overview of locomotion models and simulation frameworks

In this section, we cover two topics. Firstly, we introduce the three perhaps most widely used locomotion models which are all part of Vadere. Then, we give an overview on existing open-source crowd simulators that each support one or two of these locomotion models. From now on we refer to a simulated pedestrian as an agent while reserving the term “pedestrian” for the real world.

II-A Locomotion models

In order to simulate realistic pedestrian behavior, adequate locomotion models are necessary. Researchers of various areas have been studied the way pedestrians move and have translated their findings into mathematical models.

Historically, three development phases of locomotion models can be observed. In 1984, Stephen Wolfram introduced the idea of a cellular automaton to describe “systems constructed from many identical components, each simple, but together capable of complex behavior” [82]. Gipps and Marksjö picked up this idea to describe “interactions between pedestrians” [25] through a cellular automaton.

The second phase started with Helbing und Molnár’s publication of the social force model (SFM) in 1995 [34]. They renewed the idea of using “forces” to describe pedestrian movements that was introduced by Hirai and Tarui in 1975 [36]. In the SFM, pedestrian motion is driven by a superposition of forces called “social” forces that, according to the authors, represent a “measure for the internal motivation of the individuals to perform certain actions (movement)” [34]. The SFM was extended by several researchers such as [9] to cope with some of its problems like the treatment of inertia.

The current third phase started around 2000 when model development further branched out. ODE-based modeling turned from second order equations present in the SFM to first order equations, thus eliminating several artifacts known in the SFM [15]. The results are so-called velocity-based models [14, 73]. At the same time several more model types emerged: velocity-obstacle-based models [22, 4, 13] for collision avoidance inspired by robotics, rule-based models such as [65, 84] and models which combine different approaches like the optimal steps model (OSM) [68]. Most models have been adjusted and extended to fit the findings from interdisciplinary experiments and studies. For example, the OSM was extended based on the (inter-) personal space theory [75, 76] and the social identity theory [77].

Cognitive heuristics, social forces, Newtonian mechanics, velocity obstacles, social identities and personal space theory, computational geometry, queuing theory, cellular automata, and even fuzzy logic are ideas and techniques used in the development of modern microscopic pedestrian models. This shows that the exact nature of microscopic pedestrian behavior is open to debate. The scientific discourse will continue and the number of models will further increase. As a result, scientists need a software to compare them all.

In the following sections, we sum up the core ideas of three locomotion models which are widely used: cellular automata, forced based models and the optimal steps model.

II-A1 Common ground for all locomotion models

Topography

All locomotion approaches that we describe here use four basic modeling components: (1) agents — simulated pedestrians — who move from a (2) starting point (also called source or origin) to a (3) destination or target while avoiding (4) obstacles and other agents. These four basic components are illustrated in Fig. 2. Together they form what we call topography.

Floor fields

In addition, models use a floor field, also called scalar field [67] or navigation field, which “guides” agents from an origin to a destination. These floor fields combine attraction and repulsion. While targets attract agents, obstacles and other agents repulse. In an alternative definition floor fields encode utility for an agent modeled as “homo economicus”. Closeness to the destination increases utility, too close proximity to walls or other agents decreases utility. Floor fields can also be interpreted as a probability density function for the next move. The incorporation of the scalar fields depends on the model, but the general principle remains the same. The dominant part of most floor fields is the utility caused by proximity to the destination, or the attraction by the target. The simplest ansatz to encode proximity is to calculate the Euclidean distance from a destination to each point in the topography. The closer an agent is to the destination, the better its position. However, the Euclidean distance to the target fails whenever obstacles are located between an agent and its destination as illustrated in Fig. 3. Furthermore, it might fail even if the shortest path is free, for example, pedestrians do not necessarily follow the shortest path when passing doors [53]. Therefore, in Vadere, we only use the geodesic distance to a target. The minimal geodesic path can be the shortest as well as the fastest path [32, 48].

Solving the eikonal equation is a widely used approach to obtain the geodesic distance between a destination and each position in the topography. The eikonal equation is a non-linear partial differential equation:

[TABLE]

The solution $u$ of the eikonal equation is the travel time of a wave front that starts at the target region $\Gamma\subset\Omega$ and propagates across the topography area $\Omega$ with speed $f\geq 0$. For all positions inside obstacles, $f$ is zero, that is, the wave stops. Compare to Fig. 4. If $f=1$ everywhere else, $u(x)$ is the shortest distance to the target area $\Gamma$ starting at position $x$ while skirting obstacles. To achieve more realistic medium scale avoidance behavior, one can choose a speed function $f$ for the wave front that depends on the pedestrian density. By lowering $f$ at crowded locations, that is slowing the wave down, medium-scale avoidance of other pedestrians can be modeled [32, 48]. In this case, the floor field becomes dynamic and must be recomputed regularly.

II-A2 Cellular automata (CA)

Stephen Wolfram generalized the idea of a cellular automaton:

Cellular automata are mathematical idealizations of physical systems in which space and time are discrete, and physical quantities take on a finite set of discrete values. A cellular automaton consists of a regular uniform lattice (or “array”), usually infinite in extent, with a discrete variable at each site (“cell”). […] A cellular automaton evolves in discrete time steps, with the value of the variable at one site being affected by the values of variables at sites in its “neighborhood” on the previous time step. [81]

In the context of pedestrian dynamics, the concept of CA is implemented as follows. The topography area is divided into cells of equal shape that are either empty or occupied by a pedestrian, a target or an obstacle. The state of a cell is updated at each time step, that is, agents move from cell to cell according to certain rules. In most CA-models for pedestrian dynamics the rules depend on a floor field as described above and positions are updated instantaneously. There are several ways to define the update order of pedestrians. The order in which pedestrians are updated has an impact on the simulation outcome [69]. It is rarely parallel, to avoid collisions, and thus differs from Wolfram’s original definition of cellular automata. Furthermore, the state of a cell is not purely defined by the state of neighboring cells but also by some global information. Fig. 5 visualizes the concept of a cellular automaton at one specific time step.

The major advantage of cellular automata is their simplicity with respect to understanding, implementation and computation. Compared to other locomotion models like ODE-based models, which require integration, cellular automata are significantly less computationally expensive. Thus, CA-models were more popular in the past when computational power was a more limited resource. However, the coarse discretization of cellular automata leads to artifacts. More complex cellular automata where each agent is contained in several small cells attain a small variation of step lengths and directions [80] but not the full range. Additionally, agents tend to move along zig-zag trajectories because of the grid structure and may get stuck in narrow passages that are not resolved by the grid. Fig. 6 visualizes these artifacts.

Vadere implements cellular automata as a special case of the optimal step model where certain constraints hold. See Section II-A4. Thus, the Vadere implementation does not do justice to the computational efficiency a cellular automaton can achieve. However, it allows scientists to judge for themselves whether or not the grid artifacts would compromise the validity of their simulation study.

II-A3 Force-based models

In 1975 a first force-based model, inspired by the motion of a shoal, was introduced in Japan [36]. Four years later, [56] proposed a model inspired by forces between magnets. The best known and analyzed force-based model is Helbing’s and Molnár’s social force model (SFM) from 1995 [34]. Extensions were proposed by Helbing and his group [40, 55] as well as others [85, 52, 59, 58, 9, 47]. Agents are treated like particles that are accelerated or decelerated by “social” forces taking Newton’s second law of dynamics as a guiding principle. The primary force $F_{l}^{t}$ of all these models is the force that drives an agent $l$ towards its destination

[TABLE]

Here $v_{l}^{0}$ is the agent’s free-flow velocity, $x_{l}$ its position, $e_{l}$ the direction pointing towards the target region and $\tau_{l}$ the agent’s reaction time. If the agent can move unhindered, that is, if there are no obstacles or other agents, this is the only force affecting the agent. In the following, we describe the SFM in its original form without its extensions.

While obstacles always evoke a repulsive force pushing agents away, forces defined between two agents can either attract, e. g. to model groups, or repulse. Acceleration is described through

[TABLE]

where $w_{l}$ is the unrestricted velocity induced by the sum of all forces $F_{l}$ acting on agent $l$ [34]. The $fluctuation$ term was added to take random variations into account. The actual velocity $\dot{x}_{l}$ of agent $l$ is limited to some maximum speed $v^{max}_{l}$:

[TABLE]

In its original version, the direction towards the target $e_{l}$ is the normed vector pointing to the closest point of the target region. This entails numerical problems when an agent “steps” on the target [47]. Instead the normed gradient of $u(x_{l})$ at the agent’s position $x_{l}$, defined by Eq. 1, that is

[TABLE]

gives a more sophisticated definition of the target direction [51] which is used in Vadere.

The social force model has been reported to reproduce collective phenomena like lane formation, the “faster-is-slower” effect, oscillations at bottlenecks and clogging at exit doors [9]. Johansson et al. provide an overview of extensions of the social force model, such as the inclusion of physical forces, a constrained interaction range and limiting the number of other pedestrians considered [41]. The social force model is very popular, but it has also been criticized for artifacts that stem from its proximity to Newtonian mechanics, namely oscillating trajectories and overlapping agents [7, 15], and for numerical issues [47]. Another problem of all force-based models arises with the multiple roles of the relaxation time $\tau_{l}$ in Eq. 2. It affects how precisely agents follow their preferred path, and at the same time, how they avoid collisions [41]. These two behaviors may not be correlated. The authors believe that it is up to the scientists to decide which artifacts can be tolerated in view of their specific research questions. Vadere facilitates this decision: scientists can visually compare simulation outcomes for test scenarios of their choosing.

II-A4 Optimal steps model (OSM)

The optimal steps model (OSM) defines motion by a series of discrete footsteps. Like cellular automata-based but unlike ODE-based models, each footstep is modeled explicitly as a discrete time event. It starts and ends at a specific time but is performed instantaneously. The model was introduced in [68] and enhanced in [75, 76, 77]. In this contribution we refer to the latest version of the OSM described in [77]. As many other models the OSM seeks a balance of goals: reach a target while avoiding obstacles and other agents.

During the simulation, each agent $l$ performs a series of steps as depicted in Fig. 7(a). The next foot position is found by optimizing utility within a circle around the agent. The utility is encoded in a floor field $P_{l}$ as described in Section II-A1. $P_{l}$ can also be interpreted as a potential field. The radius $s^{0}_{l}$ of the step circle is correlated with the agent’s free-flow velocity $v^{0}_{l}$. More precisely

[TABLE]

where the error term $\epsilon$ is assumed to be normally distributed [68]. In crowded situations the agents make shorter step, shorter than $s^{0}_{l}$, while the duration between steps, $s^{0}_{l}/v^{0}_{l}$, remains unchanged. Thus deceleration in a crowd is an emergent behavior of the OSM. Vadere’s OSM uses an event driven update scheme [11] and each step of an agent is an event. Stepping events of multiple agents are ordered in an event queue and executed accordingly [69].

The potential field $P_{l}$ of an agent $l$ is given by a sum of sub-utilities or sub-potentials: $P_{t}$ contributes attraction to the target or utility from proximity to the target and is given by the solution of the eikonal Eq. 1 for all agents that share a target. It is defined globally, that is, on the whole simulation area. $P_{p,l,i}$ causes local repulsion (or dips in utility) by other agents, and $P_{o,j}$ local repulsion from obstacles:

[TABLE]

with $n$ agents and $m$ obstacles in the topography (compare [68] and [64, p. 63]).

The agent potential $P_{p,l,i}$ translates the theory of (inter-) personal space [30] into a mathematical formula. $P_{p,l,i}$ is the sum of three functions: $p^{\text{per}}_{l,i}$, $p^{\text{int}}_{l,i}$ and $p^{\text{tor}}_{l,i}$ which correspond to the personal space, the intimate space and the torsos of agents $l$ and $i$.

[TABLE]

with

[TABLE]

Here $y_{i}$ is the position, $r_{i}$ the radius of the torso of agent $i$ and $\delta^{\text{per}}_{l}$, $\delta^{\text{int}}_{l}$ are the radii of the personal and intimate space of agent $l$. $d_{i}(x)$ gives the Euclidean distance between $y_{i}$ and $x$, that is,

[TABLE]

In the current implementation of the OSM the personal spaces and radii of all agents are equal. For more details we refer to [76, 78].

Let $x_{k}$ be the position of an agent $l$, then its next position $x_{k+1}$ minimizes $P_{l}$ (or maximizes $-P_{l}$) with respect to all reachable positions, that is,

[TABLE]

with

[TABLE]

Different floor field definitions can be used to reproduce competitive jostling or more cooperative queuing at bottlenecks [89] and several other behaviors [76, 66, 49, 48]. The optimization is robust and with carefully designed potentials, the OSM is free of overlaps and oscillations.

Using the OSM leads to solving many optimization problems. For each step of each agent a non-trivial optimization problem has to be solved. This optimization is computational expensive and requires most of the overall computation time. Introducing more complex potential functions complicates the evaluation of $P_{l}$ which contributes directly to the computation time of the optimization. This is aggravated by fact that a strict event-driven update hinders parallelization of the computation. Therefore, simulating thousands of agents in real-time using the OSM with Vadere is not yet possible. Performance improvement is one of the topics we are currently working on.

Mimicking cellular automata with the optimal steps model

The OSM can mimic motion in a cellular automaton by restricting the optimization to equidistant points on a circle [68]. See Fig. 8.

II-A5 Other locomotion models

We present a short description of other models that are implemented in Vadere. For details we refer to the respective publications.

Gradient navigation model (GNM)

The gradient navigation model is similar to velocity-based models that avoid the acceleration equation of the harmonic oscillator characteristic for force-based models. The GNM uses a superposition of gradients of distance functions to directly change the direction of the velocity vector [14]. Speed is a scalar that is adapted according to the difference between the desired speed and the actual speed while considering that reaction is delayed. Therefore, the relaxation time $\tau$ is disentangled from path finding.

Behavioral heuristics model (BHM)

The behavioral heuristics model (BHM) follows a completely different approach [65]: simple heuristics rooted in cognitive psychology determine each agent’s next step. Each agent uses one of four heuristics that correspond to four levels of cognitive capacity. The simplest is the step or wait heuristic: The agent checks whether the next full step in the desired direction leads to a collision. If so, it waits and if not, it steps forward. The tangential evasion heuristic allows the agent to evade another agent in its path tangentially, if the evasion step does not cause a collision. This requires two additional collision tests. Two more levels of cognitive effort are modeled. See Fig. 9.

Steering behaviors model

Reynolds’ steering behavior model offers simulation as an alternative to scripting the path of each individual to reproduce the aggregated motion of a flock of birds, a herd of land animals, or a shoal of fish [62]. The model defines a set of steering behaviors which can be combined to establish more complex goals such as walking through a narrow corridor. Steering behaviors are motivated by the visual beauty observed in nature. Reynolds’ goal was to reproduce realistic looking motion pattern for animation and games rather than studying pedestrian behavior. Due to his target group the computational complexity of the model is low. Furthermore, the ability to combine different steering behaviors and the code accessibility furthers the software development process. New steering behaviors can be introduced without inventing a whole new model and an open-source implementation of Reynolds’ work is available on his website. Despite the different target audience, Reynolds’ model is used in pedestrian dynamics to compare it against other models. In [83], for example, the authors compare the social force model, a velocity-obstacle-based model presented in [4] and Reynolds’ steering behavior model.

II-B Existing simulation frameworks

Several companies like, PTV, LEGION and accu:rate, offer licenses for commercial crowd simulators based on microscopic models. However, their implementations are proprietary. The code cannot be analyzed to understand it in detail and to ensure that computer experiments can be reproduced exactly. This hinders comparison between models and thus the knowledge transfer between researchers that we strive for in this contribution. Therefore, we limit this discussion to open-source frameworks. The overview in Table I lists frameworks that have been documented through publications or tutorials and have undergone recent development activities. The table shows the initial release date, the programming language the simulator is based on, the number of files and the lines of code 111Lines of code excluding test code, blank lines and comments counted with “cloc” software tool. See Section A-A for more details about how lines of code were obtained.. For a more extensive, but never exhaustive overview, we refer to [78, p. 17–22].

Among the six simulators in Table I, SUMO (simulation of urban mobility) plays a special role. SUMO focuses on complete intermodal traffic systems including road vehicles, public transport and pedestrians, while FDS+Evac, JuPedSim, Menge and MomenTUMv2 concentrate on the actual pedestrian dynamics.

FDS+Evac

The Fire Dynamics Simulator (FDS) has been developed by the National Institute of Standards and Technology (NIST) since 2000 [54]. FDS started as a pure large-eddy simulator for slow flows which focuses on smoke and heat transport from fires. In the following years, the VTT Technical Research Centre of Finland joined this development and integrated the evacuation module FDS+Evac into FDS in 2007. FDS+Evac focuses on simulating human egress. The simulation framework consists of four components: (1) The simulation core which is called FDS. (2) The graphical user interface Smokeview (SMV) that is used to display the output of FDS. (3) The FDS+Evac submodule for FDS to integrate agent-based simulations of humans and (4) additional third-party tools for visualization, pre- and post-processing. FDS+Evac uses the social force model [34] to move agents in a 2-dimensional plane and offers grouping behavior and different exit selection strategies for agents [46].

JuPedSim

JuPedSim’s development is mainly driven by the Forschungszentrum Jülich. JuPedSim is a framework for the simulation of pedestrian dynamics at a microscopic level that focuses on evacuation scenarios. JuPedSim consists of four modules: (1) JPScore simulates the movement of agents. JPScore provides three models on the tactical layer: a shortest path strategy, a quickest path strategy and a cognitive map to explore the environment, e. g. to discover doors. On the operational layer, JPScore provides three continuous models based on ordinary differentials: the force-based generalized centrifugal force model [9], the collision-free velocity model [72] and the wall-avoidance model [27]. (2) JPSreport includes tools for density, velocity and flow measurements to analyze agent trajectories. (3) JPSvis visualizes simulation results through 2D or 3D animations. JPSvis can be directly connected to JPScore to get an online visualization of a simulation run. (4) JPSeditor is a tool for editing model parameters and the topography.

Menge

The Menge framework originated at the University of North Carolina. Like for Vadere, the goal is to facilitate model comparison. For this, the Menge developers provide a very generic framework and invite researchers to contribute to the project. Menge breaks the simulation down into six sub-problems: (1) Target selection. (2) Plan computation: find the destination by using graphs or potential fields. (3) Plan adaption: use local navigation to find the preferred velocity (4). Motion synthesis: this means the physical motion of an agent including head, shoulder and feet movement which is not yet addressed within the Menge framework. (5) Environmental queries: identify influencing factors which are in line-of-sight of agent. (6) Crowd systems: simulations of aggregated individuals. Compared to Vadere, Menge offers but also insists on a software structure which realizes all three levels of pedestrian behavior defined in [37]: the operational (locomotion) layer, the tactical layer, and the strategic layer. This predefined structure is valuable if the model can be mapped onto it but hampering if not. Overhead and additional complexity result in longer development times before a researcher can compare locomotion models.

MomenTUMv2

MomenTUMv2 has been developed at Technical University Munich. The focus lies on analyzing and comparing pedestrian behavior models. Like Menge, the MomenTUMv2 framework implements all levels of pedestrian behavior defined in [37], that is, the simulation as well as the software itself breaks down into strategic, tactical and operational layers. The strategic layer is responsible for the destination choice of agents. The tactical layer contains four items: (1) navigating to a destination (2) participating (e. g. in front of a stage) (3) queuing (4) searching unknown locations. The operational layer provides models for walking and waiting agents. Both models can either use a cellular automaton or a force-based model for locomotion. Compared to Vadere, and similar to Menge, the three-layered structure in the software introduces development overhead before two locomotion models can be compared.

SUMO

SUMO is spearheaded by the Institute of Transportation Systems of the German Aerospace Center (DLR). The SUMO simulator allows to evaluate infrastructure changes before implementing them in a real environment. Its scope and its user community are much larger than that of Vadere and the three other pedestrian dynamics simulators. We mention it, because in the long run, an interface between SUMO and well-established locomotion models from the pedestrian community would benefit the scientific community.

III Vadere: A framework to compare different locomotion models

The Vadere project was started in 2010 [78, p. 23]. Its main intention was and still is to facilitate development and comparison of locomotion models. Therefore, it was designed as a generic framework, but with an eye on keeping it lightweight, so that new locomotion models can be quickly implemented. In [64], the software requirements are summarized as shown in Table II. This section first introduces Vadere from a user’s perspective, and then delves into the software architecture for readers who wish to develop with Vadere.

III-A Vadere for users

The following section provides an overview of Vadere and its optional graphical user interface. The goal is to ease researchers from different domains into the first simulation steps.

III-A1 Vadere: overview

Vadere is implemented in Java programming language. Thus, it is available for GNU/Linux, MacOS and Microsoft Windows. Vadere follows the KISS principle [31]: keep it simple, stupid. For this reason, Vadere reads in simulation parameters, like the topography or an agent’s radius, from a human-readable JSON-based text file instead of using a binary format. Also, the simulation results — usually x and y coordinates for each pedestrian and a time step — are written to text files. In this way, users can use text editors to create input files for Vadere and they can open result files from Vadere with 3rd-party software like MATLAB. Furthermore, text files allow users to modify parameters quickly in an automated way. This is essential for studies where parameters must be varied and, thus, thousands of simulations must be run.

Performing simulations with Vadere requires three steps visualized in Fig. 10 and summarized below:

Create an input file for the simulation. 2. 2.

Run the simulation with the input file from (1). 3. 3.

Analyze the simulation results.

The graphical user interface supports all three steps. Step (1) and (3) can also be carried out with 3rd-party applications that a researcher might be more familiar with.

When creating input files for the simulation, so-called output processors can be used to specify what output files should be written. Different output processors exist, e. g. to write the trajectory of each agent or to write the density at each time step. It is also possible to let multiple output processors write into the same file. Listing LABEL:lst:VadereOutputFile visualizes the structure of an example output file written by Vadere.

We think that a highlight for the scientific community lies in our simple, but effective approach to make simulation results completely reproducible. When compiling Vadere from sources — which are under version control using Git — Vadere adds the commit hash to the simulation output files. The commit hash allows to exactly track with which Vadere version a simulation was executed.

III-A2 Vadere: graphical user interface

Vadere includes an optional graphical user interface (GUI) to simplify usage. The GUI has multiple features. Firstly, it provides an overview of the scenario files and the corresponding simulation outputs. Secondly, it offers a simple but effective drawing program to define the topography and to manipulate the attributes of topography elements like agents, sources, targets, obstacles and stairs. Thirdly, during the design of a simulation study, possible problems are identified and transmitted to the user, e. g. if a pedestrian is defined without a target. The fourth useful GUI feature is the possibility to visualize the simulation run online and offline. Through this monitoring option developers get an immediate visual feedback whether or not agents move “properly” [24]. Fig. 11 shows a screen shot of the Vadere GUI.

We provide an executable file, called vadere-gui.jar that includes all functionalities. In addition, we provide a console version called vadere-console.jar. that should be used to automate simulation runs, for example, when running multiple instances or running Vadere on a remote computer.

III-A3 Vadere: locomotion models supported in Vadere

Currently, Vadere supports seven locomotion models, namely the behavioral heuristics model, a simple bio-mechanics model, the gradient navigation model, the optimal steps model, an optimal velocity model, an implementation of Reynolds’ steering model and an implementation of the original social force model. The locomotion that emerges from cellular automata is be mimicked by using the optimal steps model (compare Fig. 8). This approach is much less efficient than an implementation that makes use of the grid structure to build a true automaton. Therefore, Vadere can be used to see whether a cellular automaton model is sufficiently accurate to answer a research question, but it does not do justice to the computational speed that a well-designed cellular automaton achieves.

III-B Vadere for developers

The following section shows Vadere’s software architecture in more detail. Moreover, this section sheds light on how to write a generic simulation framework that supports different locomotion models and demands minimal effort for add-ons.

III-B1 Vadere: architecture

Vadere’s architecture applies the model view controller (MVC) software pattern [23]. Therefore, Vadere is divided into three interconnected modules: state, gui and simulator. Moreover, Vadere is complemented by two supporting modules: utils and meshing. In sum, it is composed of five separated modules depicted in Fig. 12.

utils consists of utility classes implementing algorithms required by all other modules such as basic math functions, algorithms for computational geometry, or simple I/O-handling. meshing is a specialized computational geometry library that offers methods to mesh a geometry. The library’s mesh algorithms, notably our own EikMesh, are tailored for floor field computation. The library can be used in projects in and outside of the pedestrian dynamics’ community. For more information we refer to [90]. state contains topography elements like agents, targets, sources and all attributes, that is, all objects that define the simulation state. simulator is the most important module for developing new locomotion models. It contains all locomotion models, the simulation loop itself and all other controller components. The gui module contains all classes that are part of the graphical user interface. It is optional but recommended, especially for starters, since it improves usability. The MVC pattern leads to a clear separation of responsibilities for the three MVC modules within Vadere:

• •

Model (state): the model layer does not contain any logic. Instead, it is the simulation state, i. e. the composition of agents, sources, obstacles, targets and their corresponding attributes like the number of agents a source creates.

• •

Controller (simulator): the control layer contains the logic to change objects of the model layer. For instance, to update the x and y coordinates of all agents in each time step. Mainly, the control layer holds implementations for different locomotion models.

• •

View (gui): The view visualizes the current state of the model objects in form of a GUI. Note that the GUI itself implements the MVC pattern but on another level.

Figure 14 shows a package diagram containing important classes of Vadere and how these classes interact with each other.

III-B2 The simulation loop

Vadere’s core is its simulation loop. When starting a simulation run, Vadere enters the simulation loop. In each simulation step, the locomotion model changes the agents’ positions by the update call. See listing LABEL:lst:VadereSimulationLoop. Afterwards, the simulated time is incremented. Despite Vadere’s versatility its core is a single while-loop. Fig. 13 shows how the simulation loop updates agents’ positions at three different time steps using the OSM locomotion model. Listing LABEL:lst:VadereSimulationLoop alludes to the SourceController and the TargetController controller in a comment line (line 6). The SourceController spawns new agents inside the topography. The TargetController removes agents from the topography once they have reached their target. The locomotion model acts on the remaining agents after both operations have been completed.

III-B3 Including different locomotion models using the strategy pattern

Vadere’s goal is to offer a generic framework to support different locomotion models. The challenge is to keep development effort minimal. The solution idea is to provide an interface. More precisely, each locomotion model must implement a common interface that contains four methods. See Fig. 15:

• •

initialize(): replaces the constructor for the model.

• •

preLoop(): is called before the simulation loop starts.

• •

postLoop(): is called after the simulation loop has finished.

• •

update(): is called during the simulation loop.

The simulation loop in listing LABEL:lst:VadereSimulationLoop only holds the generic Model objects and invokes its update() method without knowing its concrete implementation. This approach is known as strategy pattern in software engineering. Implementing a new locomotion model in Vadere requires just to implement the four methods of the Model interface. At each time step, the locomotion model has access to the topography object that encapsulates all required elements like agents, obstacles and targets.

III-C Quality assurance: Unit testing and continuous integration

Errors can occur at each stage in the modeling process from real-world observations to the mathematical formulation of a locomotion model to its algorithmic formulation, and finally its implementation. See Fig. 16. Therefore, verification and validation are crucial. Through verification we want to assure that the software fulfills the requirements that we formulated, without questioning the requirements. The latter is the objective of validation where we interpret simulation outcomes as hypotheses derived from our model and compare those to empirical findings. While this can never be more than a failure to falsify one’s own model [60] it is essential for building trust. In view of this, we establish a verification and validation process as integral part of Vadere.

III-C1 Unit Testing

Crucial code is best developed in a test-driven manner to enforce correctness of written source code. Listing LABEL:lst:VadereUnitTestExample shows the principle of unit testing in the Vadere project with an example. We use the Java unit testing framework JUnit [1]. Vadere’s test suite currently covers 24%222Retrieve the detailed test report at https://gitlab.lrz.de/vadere/vadere/-/jobs/370587. of the productive source code excluding the View components. See Fig. 14. One could argue that this is a low coverage compared to industrial software [39], but we believe it is sufficient for a research simulator that needs to stay flexible. Also, we focus on testing core classes to make the simulations reliable while keeping development fast.

III-C2 Continuous integration and deployment

Our second strategy for error reduction is so-called continuous integration. In our case this means that a test pipeline is invoked each time the Vadere source code is modified and pushed to the source code repository. First, the test pipeline performs all unit tests. This represents the code verification. Then, special test scenarios which are defined by the RiMEA “Guideline for Microscopic Evacuation Analysis” [63, pp. 38–51] are executed. The guideline defines 15 test cases for evacuation scenarios which shall be passed by a pedestrian dynamics’ simulator. Additionally, we define 16 scenarios based on experiments published and evaluated in [86] and compare simulation results to real world data. Test scenarios serve partly as model verification and partly as model validation. Currently, for the OSM locomotion, at least 49 test runs with different parameter sets are executed. Finally, the verified and validated executable of the Vadere simulator is placed on the website http://www.vadere.org/releases/. The website hosts Vadere versions for GNU/Linux and Microsoft Windows. We use the web-based Git repository manager GitLab [26] to manage our code base. With GitLab’s pipeline feature and self-written Python scripts — which are kept in the repository as well — we are able to automate the three steps: verification, validation and deployment of Vadere. Fig. 17 summarizes all steps that are carried out during the continuous integration and deployment cycle. GitLab reports any errors during the two pipeline stages via email to the developers and provides error details through the web interface. Furthermore, we use GitLab’s issue tracker to create feature requests and bug reports. This makes the development process transparent.

IV Conclusion

In this paper, we presented the free and open-source simulation framework Vadere for pedestrian dynamics. Vadere contains implementations of several locomotion models, among them the cellular automata, the social force model and the optimal steps model to facilitate model comparison. We described Vadere’s architecture and showed how to integrate new locomotion models in a straightforward way. Each model’s implementation is verified based on JUnit tests and validated against the standard test scenarios from the RiMEA guidelines. In addition, for any change in the code both verification and validation tests are automatically run and results are communicated to the developers. This mechanism assures a high source code quality and gives developers an immediate feedback when a result is considered implausible by the scientific community.

Our vision of Vadere is a tool that encourages research within and is used by the whole interdisciplinary pedestrian dynamics community instead of just serving the purposes of our research group. We encourage each member of this interdisciplinary community to use Vadere in the way that suits him or her: as a user who conducts and analyzes simulation experiments, as a modeler who introduces new models or as a software developer who improves and extends the software.

V Acknowledgments

We thank the research office (FORWIN) of the Munich University of Applied Sciences and the Faculty Graduate Center CeDoSIA of TUM Graduate School at Technical University of Munich for their support.

Authors’ contributions

B. K. drafted the article. B. Z. revised the article, especially Section I and II-A. M. G. critically reviewed the article and provided input for the conclusion. G. K. critically revised the article and added the abstract and gave final approval for publication.

Funding

B. K. is supported by the German Federal Ministry of Education and Research through the project OPMoPS to study organized pedestrian movement in public spaces (grant no. 13N14562). B. Z. and M. G. are supported by the German Federal Ministry of Education and Research through the project S2UCRE to study the acceleration of microscopic pedestrian simulations by designing efficient and parallel algorithms (grant no. 13N14463).

Vadere contributors (in alphabetical order)

Core developers: Felix Dietrich, Michael Seitz, Isabella von Sivers, Benedikt Zönnchen; Contributors: Florian Albrecht, Benjamin Degenhart, Marion Gödel, Benedikt Kleinmeier, Daniel Lehmberg, Jakob Schöttl, Stefan Schuhbäck, Swen Stemmer, Mario Teixeira Parente, Peter Zarnitz.

Appendix A Appendix

A-A Obtain lines of code (LOCs) for different simulators

The lines of code exclude unit tests, blank lines and comments. The ”cloc” software tool 333https://github.com/AlDanial/cloc version 1.74 was used to obtain the lines of code. The hash contained in the --report-file indicates the analyzed simulator version according to the Git version control system.

⬇

JuPedSim:

cloc

--exclude-dir=Utest

--exclude-lang=XML

--report-file=jupedsim-d942c947-cloc_report.txt

jpscore/ jpseditor/ jpsreport/ jpsvis/

.

Menge:

cloc

--match-d=src

--exclude_dir=test

--report-file=menge-menge-c3eb429-cloc_report.txt

.

MomenTUMv2:

cloc

--exclude-dir=momentum-documentation,tests

--exclude-lang=HTML,CSS,XML

--report-file=momentumv2-55c8f3a-cloc_report.txt

.

SUMO:

cloc

--match-d=src

--report-file=sumo-1.0.1-cloc_report.txt

.

Vadere:

cloc

--exclude-dir=tests

--exclude-lang=JSON --report-file=vadere-87b4fe32-cloc_report.txt

.