jupedsim.simulation

Module Contents

class Simulation(*, model: jupedsim.models.collision_free_speed.CollisionFreeSpeedModel | jupedsim.models.generalized_centrifugal_force.GeneralizedCentrifugalForceModel | jupedsim.models.collision_free_speed_v2.CollisionFreeSpeedModelV2 | jupedsim.models.social_force.SocialForceModel, geometry: str | shapely.GeometryCollection | shapely.Polygon | shapely.MultiPolygon | shapely.MultiPoint | list[tuple[float, float]], dt: float = 0.01, trajectory_writer: jupedsim.serialization.TrajectoryWriter | None = None, **kwargs: Any)

Defines a simulation of pedestrian movement over a continuous walkable area.

Movement of agents is described with Journeys, Stages and Transitions. Agents can be added and removed at will. The simulation processes one step at a time. No automatic stop condition exists. You can simulate multiple disconnected walkable areas by instantiating multiple instances of simulation.

Creates a Simulation.

Parameters:

• model (CollisionFreeSpeedModel | GeneralizedCentrifugalForceModel | CollisionFreeSpeedModelV2) – Defines the operational model used in the simulation.

• geometry (str | shapely.GeometryCollection | shapely.Polygon | shapely.MultiPolygon | shapely.MultiPoint | list[tuple[float, float]]) –

  Data to create the geometry out of. Data may be supplied as:

  • list of 2d points describing the outer boundary, holes may be added with use of excluded_areas kw-argument

  • GeometryCollection consisting only out of Polygons, MultiPolygons and MultiPoints

  • MultiPolygon

  • Polygon

  • MultiPoint forming a “simple” polygon when points are interpreted as linear ring without repetition of the start/end point.

  • str with a valid Well Known Text. In this format the same WKT types as mentioned for the shapely types are supported: GEOMETRYCOLLETION, MULTIPOLYGON, POLYGON, MULTIPOINT. The same restrictions as mentioned for the shapely types apply.

• dt (float) – Iteration step size in seconds. It is recommended to leave this at its default value.

• trajectory_writer (jupedsim.serialization.TrajectoryWriter | None) – Any object implementing the TrajectoryWriter interface. JuPedSim provides a writer that outputs trajectory data in a sqlite database. If you want other formats such as CSV you need to provide your own custom implementation.

• kwargs (Any) –

Keyword Arguments:

excluded_areas – describes exclusions from the walkable area. Only use this argument if geometry was provided as list[tuple[float, float]].

add_waypoint_stage(position: tuple[float, float], distance) → int

Add a new waypoint stage to this simulation.

Parameters:

• position (tuple[float, float]) – Position of the waypoint

• distance – Minimum distance required to reach this waypoint

Returns:

Id of the new stage.

Return type:

int

add_queue_stage(positions: list[tuple[float, float]]) → int

Add a new queue state to this simulation.

Parameters:

positions (list[tuple[float, float]]) – Ordered list of the waiting points of this queue. The first one in the list is the head of the queue while the last one is the back of the queue.

Returns:

Id of the new stage.

Return type:

int

add_waiting_set_stage(positions: list[tuple[float, float]]) → int

Add a new waiting set stage to this simulation.

Parameters:

positions (list[tuple[float, float]]) – Ordered list of the waiting points of this waiting set. The agents will fill the waiting points in the given order. If more agents are targeting the waiting, the remaining will wait at the last given point.

Returns:

Id of the new stage.

Return type:

int

add_exit_stage(polygon: str | shapely.GeometryCollection | shapely.Polygon | shapely.MultiPolygon | shapely.MultiPoint | list[tuple[float, float]]) → int

Add an exit stage to the simulation.

Parameters:

polygon (str | shapely.GeometryCollection | shapely.Polygon | shapely.MultiPolygon | shapely.MultiPoint | list[tuple[float, float]]) –

Polygon without holes representing the exit stage. Polygon can be passed as:

• list of 2d points describing the outer boundary

• GeometryCollection consisting only out of Polygons, MultiPolygons and MultiPoints

• MultiPolygon

• Polygon

• MultiPoint forming a “simple” polygon when points are interpreted as linear ring without repetition of the start/end point.

• str with a valid Well Known Text. In this format the same WKT types as mentioned for the shapely types are supported: GEOMETRYCOLLETION, MULTIPOLYGON, POLYGON, MULTIPOINT. The same restrictions as mentioned for the shapely types apply.

Returns:

Id of the added exit stage.

Return type:

int

add_direct_steering_stage() → int

Add an direct steering stage to the simulation.

This stage allows a direct control of the target the agent is walking to. Thus, it will bypass the tactical and stragecial level of the simulation, but the operational level will still be active.

Important

A direct steering stage can only be used if it is the only stage in a Journey.

Returns:

Id of the added direct steering stage.

Return type:

int

add_journey(journey: jupedsim.journey.JourneyDescription) → int

Add a journey to the simulation.

Parameters:

journey (jupedsim.journey.JourneyDescription) – Description of the journey.

Returns:

Id of the added Journey.

Return type:

int

add_agent(parameters: jupedsim.models.generalized_centrifugal_force.GeneralizedCentrifugalForceModelAgentParameters | jupedsim.models.collision_free_speed.CollisionFreeSpeedModelAgentParameters | jupedsim.models.collision_free_speed_v2.CollisionFreeSpeedModelV2AgentParameters | jupedsim.models.social_force.SocialForceModelAgentParameters) → int

Add an agent to the simulation.

Parameters:

parameters (jupedsim.models.generalized_centrifugal_force.GeneralizedCentrifugalForceModelAgentParameters | jupedsim.models.collision_free_speed.CollisionFreeSpeedModelAgentParameters | jupedsim.models.collision_free_speed_v2.CollisionFreeSpeedModelV2AgentParameters | jupedsim.models.social_force.SocialForceModelAgentParameters) – Agent Parameters of the newly added model. The parameters have to match the model used in this simulation. When adding agents with invalid parameters, or too close to the boundary or other agents, this will cause an error.

Returns:

Id of the added agent.

Return type:

int

mark_agent_for_removal(agent_id: int) → bool

Marks an agent for removal.

Marks the given agent for removal in the simulation. The agent will be removed from the simulation in the start of the next iterate() call. The removal will take place before any interaction between agents will be computed.

Parameters:

agent_id (int) – Id of the agent marked for removal

Returns:

marking for removal was successful

Return type:

bool

removed_agents() → list[int]

All agents (given by Id) removed in the last iteration.

All agents removed from the simulation since the last call of iterate(). These agents are can no longer be accessed.

Returns:

Ids of all removed agents since the last call of iterate().

Return type:

list[int]

iterate(count: int = 1) → None

Advance the simulation by the given number of iterations.

Parameters:

count (int) – Number of iterations to advance

Return type:

None

switch_agent_journey(agent_id: int, journey_id: int, stage_id: int) → None

Switch agent to the given journey at the given stage.

Parameters:

• agent_id (int) – Id of the agent to switch

• journey_id (int) – Id of the new journey to follow

• stage_id (int) – Id of the stage in the new journey the agent continues with

Return type:

None

agent_count() → int

Number of agents in the simulation.

Returns:

Number of agents in the simulation.

Return type:

int

elapsed_time() → float

Elapsed time in seconds since the start of the simulation.

Returns:

Time in seconds since the start of the simulation.

Return type:

float

delta_time() → float

Time step length in seconds of one iteration.

Returns:

Time step length of one iteration.

Return type:

float

iteration_count() → int

Number of iterations performed since start of the simulation.

Returns:

Number of iterations performed.

Return type:

int

agents() → Iterable[jupedsim.agent.Agent]

Agents in the simulation.

Returns:

Iterator over all agents in the simulation.

Return type:

Iterable[jupedsim.agent.Agent]

agent(agent_id) → jupedsim.agent.Agent

Access specific agent in the simulation.

Parameters:

agent_id – Id of the agent to access

Returns:

Agent instance

Return type:

jupedsim.agent.Agent

agents_in_range(pos: tuple[float, float], distance: float) → list[jupedsim.agent.Agent]

Agents within the given distance to the given position.

Parameters:

• pos (tuple[float, float]) – point around which to search for agents

• distance (float) – search radius

Returns:

List of agents within the given distance to the given position.

Return type:

list[jupedsim.agent.Agent]

agents_in_polygon(poly: str | shapely.GeometryCollection | shapely.Polygon | shapely.MultiPolygon | shapely.MultiPoint | list[tuple[float, float]]) → list[jupedsim.agent.Agent]

Return all agents inside the given polygon.

Parameters:

poly (str | shapely.GeometryCollection | shapely.Polygon | shapely.MultiPolygon | shapely.MultiPoint | list[tuple[float, float]]) –

Polygon without holes in which to check for pedestrians. Polygon can be passed as:

• list of 2d points describing the outer boundary

• GeometryCollection consisting only out of Polygons, MultiPolygons and MultiPoints

• MultiPolygon

• Polygon

• MultiPoint forming a “simple” polygon when points are interpreted as linear ring without repetition of the start/end point.

• str with a valid Well Known Text. In this format the same WKT types as mentioned for the shapely types are supported: GEOMETRYCOLLETION, MULTIPOLYGON, POLYGON, MULTIPOINT. The same restrictions as mentioned for the shapely types apply.

Returns:

All agents inside given polygon.

Return type:

list[jupedsim.agent.Agent]

get_stage(stage_id: int)

Specific stage in the simulation.

Parameters:

stage_id (int) – Id of the stage to retrieve.

Returns:

The stage object.

get_geometry() → jupedsim.geometry.Geometry

Current geometry of the simulation.

Returns:

The geometry of the simulation.

Return type:

jupedsim.geometry.Geometry

switch_geometry(geometry: jupedsim.geometry.Geometry) → None

Switch the geometry of the simulation.

Exchanges the current geometry with the new one. Checks if all agents and stages lie within the new geometry.

Parameters:

geometry (jupedsim.geometry.Geometry) – The new geometry to be used in the simulation.

Return type:

None