Menge
Modular Pedestrian Simulation Framework for Research and Development
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Scene Specification

Summary

The scene specification defines the elements of the simulation: the static obstacles, the elevation object, the spatial query mechanism, and, of course, the agent population. All of this is specified via an XML file constructed from a pre-defined set of valid tags. However, this set of tags can be extended when implementing new simulation elements by implementing the appropriate interface.

The basic scene specification XML has the following form:

<?xml version="1.0"?>
<Experiment version="2.0">
    <Common ... />
    <Model1 ... />
    ...
    <ModelN ... />

    <AgentProfile ... />
    ...
    <AgentProfile ... />

    <AgentGroup ... />
    ...
    <AgentGroup ... />

    <SpatialQuery ... />
    <Elevation ... />

    <ObstacleSet ... />
    ...
    <ObstacleSet ... />
</Experiment>

The major elements of the scene specification are:

The order of the major elements does not matter. Each section is detailed below.

Header

The header is simple. It is the same across all simulation scenarios. In addition to the standard XML boilerplate (<?xml version="1.0"?>) it contains all of the simulation specification contained in an <Experiment version="2.0"> tag. For historical reasons, the file version is 2.0. This must be specified, but it is conceivable that in the future alternative versions will be created to allow for changes which are not backwards compatible.

Global Simulation Parameters

Each pedestrian model requires values across a certain parameter space. Some of these parameters are considered unique per agent. Others are the same for all agents in the simulation – these are considered global parameters. Implementing the pedestrian model interface includes defining these global parameters. All global parameter definitions are included as child tags of the <Experiment> tag. There are some parameters which are common to all simulators (as all pedestrian models inherit from a common class). These are contained in the <Common> tag. Global parameters unique to a particular model are contained in a uniquely defined tag. This tag is a siblign to the global <Common> tag.

Currently, there is only one global simulation parameter: time step. Thus a typical <Common> tag would like this:

    <Common time_step="0.1" />

It is worth noting that this simulation time step can be overridden on the command line or in the project specification.

Agent Profile Definitions

Menge allows for crowds made up of a heterogeneous population. This heterogeneity can be realized using two different mechanisms: profiles and distributions. An agent profile reflects the idea that there may be different classifications of agents (e.g., old/young, male/female, etc.) These different classifications (or profiels) arise from the idea that the agents are possessed of quite different property values. However, inside a single profile, there can still be variability across agents with the same profile. This is done using distributions. For example, agents modeling young male pedestrians may have a mean preferred walking speed of 1.5 m/s with a standard deviation of 0.1 m/s. We may also want to simulate old females with a mean walking speed of 0.9 m/s and a standard deviation of 0.05 m/s.

Ultimately, the agent profile is directly concerned with defining per-agent parameters. We specify an agent profile in the following manner:

<AgentProfile name="PROFILE_NAME">
    <Common max_angle_vel="360" max_neighbors="10" obstacleSet="1" neighbor_dist="5" r="0.19" class="1" pref_speed="1.04" max_speed="2" max_accel="5" />
    <Model1 prop1="value1" prop2="value2"/>
    ...
    <ModelN prop1="value1" prop2="value2"/>
</AgentProfile>

The agent profile must be given a name – this is how the profile is referred to later by the <AgentGenerator> tags.

As with the global simulation parmaeters, there are common per-agent parameters and model-specific parameters. The common parameters are stored in the <Common> tag and the model-specific parmaeters are stored in a tag whose name is defined by the pedestrian model's implementation.

The <Common> tag has the following values (order doesn't matter and exclusion will cause them to be assigned a built-in, default value):

A <Model> tag has a similar structure. Each per-agent property will have a property name and value pair. For specific pedestrian models, the tag name and property key-value pairs are defined in the model (see Implementing new Pedestrian Models).

Property Variability

As shown above, every agent assigned the same profile will have the same property values. Menge provides a mechanism to define distributions of values for any or all of the properties contained in an <AgentProfile> child tag (both <Common> and <Model> tags. It looks like this (illustrated with the comomon property pref_speed):

<AgentProfile name="PROFILE_NAME">
    <Common max_angle_vel="360" max_neighbors="10" obstacleSet="1" neighbor_dist="5" r="0.19" class="1" pref_speed="1.04" max_speed="2" max_accel="5" >
        <Property name="pref_speed" dist="n" mean="1.3" std_dev="0.1" />
    </Common>
    <Model1 prop1="value1" prop2="value2"/>
    ...
    <ModelN prop1="value1" prop2="value2"/>
</AgentProfile>

Note, that the <Common> tag is no longer a self-contained tag. It now has a child tag: <Property>. The property tag is how we define variability for a particular property. We do so by sepcifying the property name (name) and a distribution (dist). In this case, we're defining a normal distribution with a mean value of 1.3 m/s and a standard deviation of 0.1 m/s. As agents are assigned this profile, their preferred speed values will be assigned according to this distribution (see Defining Distributions for more details). Any property with such a proeprty tag will have its single value overridden by the distribution.

The full simulation population can be decomposed into groups called "Agent sets". This grouping is useful for creating sets of agents with common (or similar) per-agent properties. For example, if I were simulating old and young pedestrians, one way in which the older population would differ from the younger distribution is that they would most likely have a slower preferred walking speed. The concept of "Agent set" (and its corresponding XML tag, <AgentSet>) make this possible.

Profile Inheritance

It is quite common that multiple profiles will be largely similar. In fact, one common use case is to have groups of identical agents who only differ in their visualization class (see the 4square example in Examples).

The <AgentProfile> tag has an additional property: inherits. One <AgentProfile> can refer to an earlier profile, inheriting all of its values (including property distributions). Then, only those properties that are different need be specified. Inheritance would look like this:

<AgentProfile name="source">
    <Common max_angle_vel="360" max_neighbors="10" obstacleSet="1" neighbor_dist="5" r="0.19" class="1" pref_speed="1.04" max_speed="2" max_accel="5" >
        <Property name="pref_speed" dist="n" mean="1.3" std_dev="0.1" />
    </Common>
</AgentProfile>

<AgentProfile name="child" inherits="source">
    <Common class="2"/>
</AgentProfile>

The agent profiles must appear in the correct order in the specification file. The parent profile must appear before the profiles that inherit from it.

Agent Groups

Still to come...

Spatial Queries

Still to come...

Elevation

Still to come...

Obstacle Sets

Still to come...