Documentation
Using
Populations

Populations

A Population places a group of agents in one start node. Each input except the area factor can be a fixed number or a distribution, and is sampled anew in every run.

Population 

Population(
    node,
    count,
    speed=1.2,
    pre_movement=0.0,
    start_distance=0.0,
    area_factor=1.0,
    target=None,
)
FieldMeaningUnit
nodeName of the start node
countNumber of agents. A distribution is sampled once per run and rounded.persons
speedFree walking speed $v_i^\text{max}$, sampled per agent; must be positivem/s
pre_movementTime before the agent starts walking, sampled per agents
start_distanceExtra distance walked in the start node, sampled per agentm
area_factorSpace the agent takes relative to an average adult; one fixed number for the population; must be positive
targetName of a safe node to head for; None for the nearest

Plain numbers are accepted for every distribution argument.

The default pre_movement=0.0 starts every agent at once, which Gwynne et al. call an optimistic default [11, p. 342]. Set a pre-movement time for any result that is to be read as an evacuation time (Limitations).

Speeds above 1.2 m/s have no effect on level ground

The walking speed is the smaller of $v_i^\text{max}$ and the congested speed of the node, and the density in that formula is never taken below 0.54 m⁻² (Model elements). No agent therefore walks faster than

  • 1.199 m/s on level ground, and
  • 0.922 m/s on an 18/28 cm stair,

whatever speed says. A 40 m walk at speed=1.5 takes 33.5 s, which is 40 m at 1.199 m/s. The default speed=1.2 sits at this ceiling, so sampled speeds above 1.2 m/s change nothing on level ground.

Area factor

area_factor scales the agent’s contribution to node density and to the free space of a node. A value of 2 counts the agent as two average adults, for example for a wheelchair user. The factor is a choice of this model and is not calibrated (Model elements). Above 1.88 m⁻² an agent with a large area factor waits until the node has saved supply for its whole area (update scheme).

Distributions 

Fixed(value)
Uniform(minimum, maximum)
Normal(mean, std)
LogNormal(mean, std)
Triangular(minimum, mode, maximum)
Weibull(alpha, beta)

Each takes the keyword arguments lower=0.0 and upper=None.

  • Every distribution is truncated at 0 by default. Normal(10, 20) never returns a negative value. Pass lower=None to allow them, except for start_distance, whose lower must stay at or above 0.
  • Values outside [lower, upper] are drawn again, up to 100 times. Values still outside are then clipped to the bounds. A Fixed value outside the bounds raises ValueError, and so does lower above upper (Input checks).
  • mean and std of Normal and LogNormal are those before truncation.
  • LogNormal(mean, std) takes the mean and standard deviation of the variable itself, not of its logarithm.
  • Weibull(alpha, beta) takes the scale alpha and the shape beta.

Truncation shifts the mean:

import numpy as np
from jupedsim_network import Normal

rng = np.random.default_rng(1)
print(round(Normal(10.0, 20.0).sample(rng, 100_000).mean(), 2))
print(round(Normal(10.0, 20.0, lower=None).sample(rng, 100_000).mean(), 2))

Output:

20.12
9.93

Truncated at 0, Normal(10, 20) has a mean of about 20, not 10.

Start nodes that are too full

If the agents of all populations in a node, weighted by their area factors, exceed max_density times its area, run() raises ValueError: Initial population exceeds max_density in [...]. The check happens at run(), not when the population is created, because count may be sampled.

Related

  • Running: how sampled inputs are seeded.
  • Limitations: behaviour the inputs cannot represent.
Last updated on
NetworksRunning