jupedsim

`jupedsim`#

Package Contents#

Classes#

`Agent`	Represents an Agent in the simulation.
`AnticipationVelocityModel`	Anticipation Velocity Model (AVM).
`AnticipationVelocityModelAgentParameters`	Agent parameters for Anticipation Velocity Model (AVM).
`AnticipationVelocityModelState`
`BuildInfo`
`CollisionFreeSpeedModel`	Collision Free Speed Model
`CollisionFreeSpeedModelAgentParameters`	Agent parameters for Collision Free Speed Model.
`CollisionFreeSpeedModelState`
`CollisionFreeSpeedModelV2`	Collision Free Speed Model V2
`CollisionFreeSpeedModelV2AgentParameters`	Agent parameters for Collision Free Speed Model V2.
`CollisionFreeSpeedModelV2State`
`ExitStage`	Models an exit.
`GeneralizedCentrifugalForceModel`	Parameters for Generalized Centrifugal Force Model
`GeneralizedCentrifugalForceModelAgentParameters`	Parameters required to create an Agent in the Generalized Centrifugal Force
`GeneralizedCentrifugalForceModelState`
`Geometry`	Geometry object representing the area agents can move on.
`JourneyDescription`	Used to describe a journey for construction by the `Simulation`.
`NotifiableQueueStage`	Models a queue where agents can wait until notified.
`Recording`
`RecordingAgent`	Data for a single agent at a single frame.
`RecordingFrame`	A single frame from the simulation.
`RoutingEngine`	RoutingEngine to compute the shortest paths with navigation meshes.
`Simulation`	Defines a simulation of pedestrian movement over a continuous walkable area.
`SocialForceModel`	Parameters for Social Force Model
`SocialForceModelAgentParameters`	Parameters required to create an Agent in the Social Force Model.
`SocialForceModelState`
`SqliteTrajectoryWriter`	Write trajectory data into a sqlite db
`TrajectoryWriter`	Interface for trajectory serialization
`Transition`	Describes the Transition at a stage.
`WaitingSetStage`	Models a set of waiting positions that can be activated or deactivated.
`WaitingSetState`	Create a collection of name/value pairs.
`WaypointStage`	Models a waypoint.

Functions#

`distribute_by_density`(→ list[tuple[float, float]])	Generates randomized 2D coordinates based on a desired agent density per
`distribute_by_number`(→ list[tuple[float, float]])	Generates specified number of randomized 2D coordinates.
`distribute_by_percentage`(*, polygon, percent, ...[, ...])	Generates randomized 2D coordinates that fill the specified area to a
`distribute_in_circles_by_density`(→ list[tuple[float, ...)	Generates randomized 2D coordinates in a user defined number of rings
`distribute_in_circles_by_number`(→ list[tuple[float, ...)	Generates randomized 2D coordinates in a user defined number of rings.
`distribute_until_filled`(→ list[tuple[float, float]])	Generates randomized 2D coordinates that fill the specified area.
`get_build_info`(→ BuildInfo)	Get build information about jupedsim.
`set_debug_callback`(→ None)	Set receiver for debug messages.
`set_error_callback`(→ None)	Set receiver for error messages.
`set_info_callback`(→ None)	Set receiver for info messages.
`set_warning_callback`(→ None)	Set receiver for warning messages.

Attributes#

`__commit__`	Commit id that was used to build this module.
`__compiler__`	Id of the compiler used to build the native portion of this module.
`__version__`	The version of this module.

exception AgentNumberError(message)[source]#

Bases: Exception

Common base class for all non-exit exceptions.

message#

exception IncorrectParameterError(message)[source]#

Bases: Exception

Common base class for all non-exit exceptions.

message#

exception NegativeValueError(message)[source]#

Bases: Exception

Common base class for all non-exit exceptions.

message#

exception OverlappingCirclesError(message)[source]#

Bases: Exception

Common base class for all non-exit exceptions.

message#

class Agent(backing)[source]#

Represents an Agent in the simulation.

Agent objects are always retrieved from the simulation and never created directly.

Agents can be accessed with:

# a specific agent
sim.agent(id)

# all agents as iterator
sim.agents()

# agents in a specific distance to a point as iterator
sim.agents_in_range(position, distance)

# agents in a polygon as iterator
sim.agents_in_polygon(polygon)

Note

You need to be aware that currently there are no checks done when setting properties on an Agent instance. For example it is possible to set an Agent position outside the walkable area of the Simulation resulting in a crash.

property id: int#: Numeric id of the agent in this simulation.

property journey_id: int#: Id of the JourneyDescription the agent is currently following.

property model: jupedsim.models.generalized_centrifugal_force.GeneralizedCentrifugalForceModelState | jupedsim.models.collision_free_speed.CollisionFreeSpeedModelState | jupedsim.models.collision_free_speed_v2.CollisionFreeSpeedModelV2State | jupedsim.models.anticipation_velocity_model.AnticipationVelocityModelState | jupedsim.models.social_force.SocialForceModelState#: Access model specific state of this agent.

property orientation: tuple[float, float]#: Orientation of the agent.

property position: tuple[float, float]#: Position of the agent.

property stage_id: int#: Id of the Stage the Agent is currently targeting.

property target: tuple[float, float]#

Current target of the agent.

Can be used to directly steer an agent towards the given coordinate. This will bypass the strategical and tactical level, but the operational level will still be active.

Important

If the agent is not in a Journey with a DirectSteering stage, any change will be ignored.

Important

When setting the target, the given coordinates must lie within the walkable area. Otherwise, an error will be thrown at the next iteration call.

Returns:: Current target of the agent.

class AnticipationVelocityModel[source]#

Anticipation Velocity Model (AVM).

The AVM incorporates pedestrian anticipation, divided into three phases: 1. Perception of the current situation. 2. Prediction of future situations. 3. Strategy selection leading to action.

This model quantitatively reproduces bidirectional pedestrian flow by accounting for: - Anticipation of changes in neighboring pedestrians’ positions. - The strategy of following others’ movement. The AVM is a model that takes into consideration

the anticipation of pedestrians. For this, the process of anticipation is divided into three parts: - perception of the actual situation, - prediction of a future situation and - selection of a strategy leading to action.

A general description of the AVM can be found in the originating publication https://doi.org/10.1016/j.trc.2021.103464

pushout_strength#: The pushout mechanism ensures agents maintain a safe distance

from walls by adding a small outward component to their movement when within the

critical wall distance. This outward component, scaled by `pushoutStrength`,

combines with the parallel component of the agent's direction to create smooth,

gliding behavior along walls.

rng_seed#: seed value of internally used rng. If not explicitly set this value will be chosen randomly.

pushout_strength: float = 0.3#

rng_seed: int#

class AnticipationVelocityModelAgentParameters[source]#

Agent parameters for Anticipation Velocity Model (AVM).

See publication for more details about this model https://doi.org/10.1016/j.trc.2021.103464

Note

Instances of this type are copied when creating the agent, you can safely create one instance of this type and modify it between calls to add_agent

E.g.:

positions = [...] # List of initial agent positions
params = AnticipationVelocityModelAgentParameters(desired_speed=0.9) # all agents are slower
for p in positions:
    params.position = p
    sim.add_agent(params)

position#: Position of the agent.

time_gap#: Time constant that describe how fast pedestrian close gaps.

desired_speed#: Maximum speed of the agent.

radius#: Radius of the agent.

journey_id#: Id of the journey the agent follows.

stage_id#: Id of the stage the agent targets.

strength_neighbor_repulsion#: Strength of the repulsion from neighbors

range_neighbor_repulsion#: Range of the repulsion from neighbors

wall_buffer_distance#: Buffer distance of agents to the walls.

anticipation_time#: Anticipation time of an agent.

reaction_time#: reaction time of an agent to change its direction.

anticipation_time: float = 1.0#

desired_speed: float = 1.2#

journey_id: int = 0#

position: tuple[float, float] = (0.0, 0.0)#

radius: float = 0.2#

range_neighbor_repulsion: float = 0.1#

reaction_time: float = 0.3#

stage_id: int = 0#

strength_neighbor_repulsion: float = 8.0#

time_gap: float = 1.06#

wall_buffer_distance: float = 0.1#

class AnticipationVelocityModelState(backing)[source]#

property anticipation_time: float#: Anticipation time of this agent.

property desired_speed: float#: desired Speed of this agent.

property radius: float#: Radius of this agent.

property range_neighbor_repulsion: float#: Range of the repulsion from neighbors of this agent.

property reaction_time: float#: Reaction time of this agent.

property strength_neighbor_repulsion: float#: Strength of the repulsion from neighbors of this agent.

property time_gap: float#

property wall_buffer_distance#: Wall buffer distance of agent to walls.

class BuildInfo[source]#

property compiler: str#

Compiler the native code was compiled with.

Returns:: Compiler identification.

property compiler_version: str#

Compiler version the native code was compiled with.

Returns:: Compiler version number.

property git_branch: str#

Branch this commit was crated from.

Returns:: name of the branch this version was build from.

property git_commit_date: str#

Date this commit was created.

Returns:: Date the commit of this version as string.

property git_commit_hash: str#

SHA1 commit hash of this version.

Returns:: SHA1 of this version.

property library_version: str#

class CollisionFreeSpeedModel[source]#

Collision Free Speed Model

A general description of the Collision Free Speed Model can be found in the originating publication https://arxiv.org/abs/1512.05597

A more detailed description can be found at https://pedestriandynamics.org/models/collision_free_speed_model/

strength_neighbor_repulsion#: Strength of the repulsion from neighbors

range_neighbor_repulsion#: Range of the repulsion from neighbors

strength_geometry_repulsion#: Strength of the repulsion from geometry boundaries

range_geometry_repulsion#: Range of the repulsion from geometry boundaries

range_geometry_repulsion: float = 0.02#

range_neighbor_repulsion: float = 0.1#

strength_geometry_repulsion: float = 5.0#

strength_neighbor_repulsion: float = 8.0#

class CollisionFreeSpeedModelAgentParameters(*, position: tuple[float, float] = (0.0, 0.0), time_gap: float = 1.0, desired_speed: float = 1.2, radius: float = 0.2, journey_id: int = 0, stage_id: int = 0, v0: float | None = None)[source]#

Agent parameters for Collision Free Speed Model.

See the scientific publication for more details about this model https://arxiv.org/abs/1512.05597

Note

Instances of this type are copied when creating the agent, you can safely create one instance of this type and modify it between calls to add_agent

E.g.:

positions = [...] # List of initial agent positions
params = CollisionFreeSpeedModelAgentParameters(desired_speed=0.9) # all agents are slower
for p in positions:
    params.position = p
    sim.add_agent(params)

position#: Position of the agent.

time_gap#: Time constant that describe how fast pedestrian close gaps.

desired_speed#: Maximum speed of the agent.

radius#: Radius of the agent.

journey_id#: Id of the journey the agent follows.

stage_id#: Id of the stage the agent targets.

desired_speed: float = 1.2#

journey_id: int = 0#

position: tuple[float, float] = (0.0, 0.0)#

radius: float = 0.2#

stage_id: int = 0#

time_gap: float = 1.0#

property v0: float#

class CollisionFreeSpeedModelState(backing)[source]#

property desired_speed: float#: desired Speed of this agent.

property radius: float#: Radius of this agent.

property time_gap: float#

property v0: float#: Maximum speed of this agent.

class CollisionFreeSpeedModelV2[source]#

Collision Free Speed Model V2

This is a variation of the Collision Free Speed Model where geometry and neighbor repulsion are individual agent parameters instead of global parameters.

A general description of the Collision Free Speed Model can be found in the originating publication https://arxiv.org/abs/1512.05597

A more detailed description can be found at https://pedestriandynamics.org/models/collision_free_speed_model/

class CollisionFreeSpeedModelV2AgentParameters(*, position: tuple[float, float] = (0.0, 0.0), time_gap: float = 1.0, desired_speed: float = 1.2, v0: float | None = None, radius: float = 0.2, journey_id: int = 0, stage_id: int = 0, strength_neighbor_repulsion: float = 8.0, range_neighbor_repulsion: float = 0.1, strength_geometry_repulsion: float = 5.0, range_geometry_repulsion: float = 0.02)[source]#

Agent parameters for Collision Free Speed Model V2.

See the scientific publication for more details about this model https://arxiv.org/abs/1512.05597

Note

Instances of this type are copied when creating the agent, you can safely create one instance of this type and modify it between calls to add_agent

E.g.:

positions = [...] # List of initial agent positions
params = CollisionFreeSpeedModelV2AgentParameters(desired_speed=0.9) # all agents are slower
for p in positions:
    params.position = p
    sim.add_agent(params)

position#: Position of the agent.

time_gap#: Time constant that describe how fast pedestrian close gaps.

desired_speed#: Maximum speed of the agent.

radius#: Radius of the agent.

journey_id#: Id of the journey the agent follows.

stage_id#: Id of the stage the agent targets.

strength_neighbor_repulsion#: Strength of the repulsion from neighbors

range_neighbor_repulsion#: Range of the repulsion from neighbors

strength_geometry_repulsion#: Strength of the repulsion from geometry boundaries

range_geometry_repulsion#: Range of the repulsion from geometry boundaries

desired_speed: float = 1.2#

journey_id: int = 0#

position: tuple[float, float] = (0.0, 0.0)#

radius: float = 0.2#

range_geometry_repulsion: float = 0.02#

range_neighbor_repulsion: float = 0.1#

stage_id: int = 0#

strength_geometry_repulsion: float = 5.0#

strength_neighbor_repulsion: float = 8.0#

time_gap: float = 1.0#

property v0: float#

class CollisionFreeSpeedModelV2State(backing)[source]#

property desired_speed: float#: desired Speed of this agent.

property radius: float#: Radius of this agent.

property range_geometry_repulsion: float#: Range of the repulsion from geometry boundaries of this agent.

property range_neighbor_repulsion: float#: Range of the repulsion from neighbors of this agent.

property strength_geometry_repulsion: float#: Strength of the repulsion from geometry boundaries of this agent.

property strength_neighbor_repulsion: float#: Strength of the repulsion from neighbors of this agent.

property time_gap: float#

property v0: float#: Maximum speed of this agent.

class ExitStage(backing)[source]#

Models an exit.

Agents entering the polygon defining the exit will be removed at the beginning of the next iteration, i.e. agents will be inside the specified polygon for one frame.

count_targeting()[source]#

Returns:: Number of agents currently targeting this stage.

class GeneralizedCentrifugalForceModel[source]#

Parameters for Generalized Centrifugal Force Model

All attributes are initialized with reasonably good defaults.

strength_neighbor_repulsion#: Strength of the repulsion from neighbors

strength_geometry_repulsion#: Strength of the repulsion from geometry boundaries

max_neighbor_interaction_distance#: cut-off-radius for ped-ped repulsion (r_c in FIG. 7)

max_geometry_interaction_distance#: cut-off-radius for ped-wall repulsion (r_c in FIG. 7)

max_neighbor_interpolation_distance#: distance of interpolation of repulsive force for ped-ped interaction (r_eps in FIG. 7)

max_geometry_interpolation_distance#: distance of interpolation of repulsive force for ped-wall interaction (r_eps in FIG. 7)

max_neighbor_repulsion_force#: maximum of the repulsion force for ped-ped interaction by contact of ellipses (f_m in FIG. 7)

max_geometry_repulsion_force#: maximum of the repulsion force for ped-wall interaction by contact of ellipses (f_m in FIG. 7)

max_geometry_interaction_distance: float = 2#

max_geometry_interpolation_distance: float = 0.1#

max_geometry_repulsion_force: float = 3#

max_neighbor_interaction_distance: float = 2#

max_neighbor_interpolation_distance: float = 0.1#

max_neighbor_repulsion_force: float = 9#

strength_geometry_repulsion: float = 0.2#

strength_neighbor_repulsion: float = 0.3#

class GeneralizedCentrifugalForceModelAgentParameters(*, speed: float = 0.0, desired_direction: tuple[float, float] = (0.0, 0.0), position: tuple[float, float] = (0.0, 0.0), orientation: tuple[float, float] = (1.0, 0.0), journey_id: int = -1, stage_id: int = -1, mass: float = 1, tau: float = 0.5, desired_speed: float = 1.2, a_v: float = 1, a_min: float = 0.2, b_min: float = 0.2, b_max: float = 0.4, v0=None, e0=None)[source]#

Parameters required to create an Agent in the Generalized Centrifugal Force Model.

See the scientific publication for more details about this model https://arxiv.org/abs/1008.4297

Note

Instances of this type are copied when creating the agent, you can safely create one instance of this type and modify it between calls to add_agent

E.g.:

positions = [...] # List of initial agent positions
params = GeneralizedCentrifugalForceModelAgentParameters(speed=0.9) # all agents are slower
for p in positions:
    params.position = p
    sim.add_agent(params)

speed#: Speed of the agent.

desired_direction#: Desired direction of the agent.

position#: Position of the agent.

orientation#: Orientation of the agent.

journey_id#: Id of the journey the agent follows.

stage_id#: Id of the stage the agent targets.

mass#: Mass of the agent.

tau#: Time constant that describes how fast the agent accelerates to its desired speed (v0).

desired_speed#: Maximum speed of the agent.

a_v#: Stretch of the ellipsis semi-axis along the movement vector.

a_min#: Minimum length of the ellipsis semi-axis along the movement vector.

b_min#: Minimum length of the ellipsis semi-axis orthogonal to the movement vector.

b_max#: Maximum length of the ellipsis semi-axis orthogonal to the movement vector.

a_min: float = 0.2#

a_v: float = 1#

b_max: float = 0.4#

b_min: float = 0.2#

desired_direction: tuple[float, float] = (0.0, 0.0)#

desired_speed: float = 1.2#

property e0: tuple[float, float]#

journey_id: int = -1#

mass: float = 1#

orientation: tuple[float, float] = (1.0, 0.0)#

position: tuple[float, float] = (0.0, 0.0)#

speed: float = 0.0#

stage_id: int = -1#

tau: float = 0.5#

class GeneralizedCentrifugalForceModelState(backing)[source]#

property a_min: float#: Minimum length of the ellipsis semi-axis along the movement vector.

property a_v: float#: Stretch of the ellipsis semi-axis along the movement vector.

property b_max: float#: Maximum length of the ellipsis semi-axis orthogonal to the movement vector.

property b_min: float#: Minimum length of the ellipsis semi-axis orthogonal to the movement vector.

property desired_direction: float#: desired direction of this agent.

property desired_speed: float#: desired Speed of this agent.

property e0: tuple[float, float]#: Desired direction of this agent.

property speed: float#: Speed of this agent.

property tau: float#

property v0: float#: Maximum speed of this agent.

class Geometry(obj: jupedsim.native.Geometry)[source]#

Geometry object representing the area agents can move on.

Gain access to the simulation’s walkable area by calling:

sim.get_geometry()

as_wkt() → str[source]#

_summary_

Returns:: _description_
Return type:: String

boundary() → list[tuple[float, float]][source]#

Access the boundary polygon of the walkable area.

Returns:: List of 2d points describing the polygon.

holes() → list[list[tuple[float, float]]][source]#

Access holes (inner boundaries) of the walkable area.

Returns:: A list of polygons forming holes inside the boundary.

class JourneyDescription(stage_ids: list[int] | None = None)[source]#

Used to describe a journey for construction by the Simulation.

A Journey describes the desired stations an agent should take when moving through the simulation space. A journey is described by a graph of stages (nodes) and transitions (edges). See Transition for an overview of the possible transitions.

add(stages: int | list[int]) → None[source]#

Add additional stage or stages.

Parameters:: stages – A single stage id or a list of stage ids.

set_transition_for_stage(stage_id: int, transition: Transition) → None[source]#

Set a new transition for the specified stage.

Any prior set transition for this stage will be removed.

Parameters:

stage_id – id of the stage to set the transition for.
transition – transition to set

class NotifiableQueueStage(backing)[source]#

Models a queue where agents can wait until notified.

The queues waiting positions are predefined and agents will wait on the first empty position. When agents leave the queue the remaining waiting agents move up. If there are more agents trying to enqueue than there are waiting positions defined the overflow agents will wait at the last waiting position in the queue.

Note

This type is used to interact with an already created stage. To create a stage of this type see Simulation

count_enqueued() → int[source]#

Returns:: Number of agents currently enqueued at this stage.

count_targeting() → int[source]#

Returns:: Number of agents currently targeting this stage.

enqueued() → list[int][source]#

Access the ids of all enqueued agents in order they are waiting at the queue.

Returns:: list of enqueued agents ordered by their position in the queue.

pop(count) → None[source]#

Pop count number of agents from the front of the queue.

Parameters:: count – Number of agents to be popped from the front of the queue

class Recording(db_connection_str: str, uri=False)[source]#

bounds() → jupedsim.internal.aabb.AABB[source]#: Get bounds of the position data contained in this recording.

frame(index: int) → RecordingFrame[source]#

Access a single frame of the recording.

Parameters:: index (int) – index of the frame to access.
Returns:: A single frame.

geometry() → shapely.GeometryCollection[source]#

Access this recordings’ geometry.

Returns:: walkable area of the simulation that created this recording.

geometry_id_for_frame(frame_id) → int[source]#

db#

property fps: float#

How many frames are stored per second.

Returns:: Frames per second of this recording.

property num_frames: int#

Access the number of frames stored in this recording.

Returns:: Number of frames in this recording.

class RecordingAgent[source]#

Data for a single agent at a single frame.

id: int#

orientation: tuple[float, float]#

position: tuple[float, float]#

class RecordingFrame[source]#

A single frame from the simulation.

agents: list[RecordingAgent]#

index: int#

RoutingEngine to compute the shortest paths with navigation meshes.

compute_waypoints(frm: tuple[float, float], to: tuple[float, float]) → list[tuple[float, float]][source]#

Computes shortest path between specified points.

Parameters:

geometry –
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.
frm – point from which to find the shortest path
to – point to which to find the shortest path

Keyword Arguments:

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

Returns:

List of points (path) from ‘frm’ to ‘to’ including from and to.

edges_for(vertex_id: int)[source]#

is_routable(p: tuple[float, float]) → bool[source]#

Tests if the supplied point is inside the underlying geometry.

Returns:: If the point is inside the geometry.

mesh() → tuple[list[tuple[float, float]], list[list[int]]][source]#

Access the navigation mesh geometry.

The navigation mesh is store as a collection of convex polygons in CCW order.

The returned data is to be interpreted as:

tuple[
    list[tuple[float, float]], # All vertices in this mesh.
    list[ # List of polygons
        list[int] # List of indices into the vertices that compose this polygon in CCW order
    ]
]

Returns:: A tuple of vertices and list of polygons which in turn are a list of indices tuple[list[tuple[float, float]],list[list[int]]]

class Simulation(*, model: jupedsim.models.collision_free_speed.CollisionFreeSpeedModel | jupedsim.models.generalized_centrifugal_force.GeneralizedCentrifugalForceModel | jupedsim.models.collision_free_speed_v2.CollisionFreeSpeedModelV2 | jupedsim.models.anticipation_velocity_model.AnticipationVelocityModel | 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)[source]#

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.

add_agent(parameters: jupedsim.models.generalized_centrifugal_force.GeneralizedCentrifugalForceModelAgentParameters | jupedsim.models.collision_free_speed.CollisionFreeSpeedModelAgentParameters | jupedsim.models.collision_free_speed_v2.CollisionFreeSpeedModelV2AgentParameters | jupedsim.models.anticipation_velocity_model.AnticipationVelocityModelAgentParameters | jupedsim.models.social_force.SocialForceModelAgentParameters) → int[source]#

Add an agent to the simulation.

Parameters:: parameters – 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.

add_direct_steering_stage() → int[source]#

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.

Add an exit stage to the simulation.

Parameters:

polygon –

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.

add_journey(journey: jupedsim.journey.JourneyDescription) → int[source]#

Add a journey to the simulation.

Parameters:: journey – Description of the journey.
Returns:: Id of the added Journey.

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

Add a new queue state to this simulation.

Parameters:: positions – 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.

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

Add a new waiting set stage to this simulation.

Parameters:: positions – 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.

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

Add a new waypoint stage to this simulation.

Parameters:

position – Position of the waypoint
distance – Minimum distance required to reach this waypoint

Returns:

Id of the new stage.

agent(agent_id) → jupedsim.agent.Agent[source]#

Access specific agent in the simulation.

Parameters:: agent_id – Id of the agent to access
Returns:: Agent instance

agent_count() → int[source]#

Number of agents in the simulation.

Returns:: Number of agents in the simulation.

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

Agents in the simulation.

Returns:: Iterator over all agents in the simulation.

Return all ids for agents inside the given polygon.

Parameters:

poly –

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 ids for agents inside given polygon.

agents_in_range(pos: tuple[float, float], distance: float) → list[int][source]#

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

Parameters:

pos – point around which to search for agents
distance – search radius

Returns:

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

delta_time() → float[source]#

Time step length in seconds of one iteration.

Returns:: Time step length of one iteration.

elapsed_time() → float[source]#

Elapsed time in seconds since the start of the simulation.

Returns:: Time in seconds since the start of the simulation.

get_geometry() → jupedsim.geometry.Geometry[source]#

Current geometry of the simulation.

Returns:: The geometry of the simulation.

get_stage(stage_id: int)[source]#

Specific stage in the simulation.

Parameters:: stage_id – Id of the stage to retrieve.
Returns:: The stage object.

iterate(count: int = 1) → None[source]#

Advance the simulation by the given number of iterations.

Parameters:: count – Number of iterations to advance

iteration_count() → int[source]#

Number of iterations performed since start of the simulation.

Returns:: Number of iterations performed.

mark_agent_for_removal(agent_id: int) → bool[source]#

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 – Id of the agent marked for removal
Returns:: marking for removal was successful

removed_agents() → list[int][source]#

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().

switch_agent_journey(agent_id: int, journey_id: int, stage_id: int) → None[source]#

Switch agent to the given journey at the given stage.

Parameters:

agent_id – Id of the agent to switch
journey_id – Id of the new journey to follow
stage_id – Id of the stage in the new journey the agent continues with

switch_geometry(geometry: jupedsim.geometry.Geometry) → None[source]#

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 – The new geometry to be used in the simulation.

class SocialForceModel(*, body_force: float = 120000, friction: float = 240000, bodyForce=None)[source]#

Parameters for Social Force Model

All attributes are initialized with reasonably good defaults.

See the scientific publication for more details about this model https://doi.org/10.1038/35035023

body_force#: describes the strength with which an agent is influenced by pushing forces from obstacles and neighbors in its direct proximity. [in kg s^-2] (is called k)

friction#: describes the strength with which an agent is influenced by frictional forces from obstacles and neighbors in its direct proximity. [in kg m^-1 s^-1] (is called \(\kappa\))

property bodyForce: float#

body_force: float = 120000#

friction: float = 240000#

class SocialForceModelAgentParameters(position: tuple[float, float] = (0.0, 0.0), orientation: tuple[float, float] = (0.0, 0.0), journey_id: int = -1, stage_id: int = -1, velocity: tuple[float, float] = (0.0, 0.0), mass: float = 80.0, desired_speed: float = 0.8, reaction_time: float = 0.5, agent_scale: float = 2000, obstacle_scale: float = 2000, force_distance: float = 0.08, radius: float = 0.3, desiredSpeed=None, reactionTime=None, agentScale=None, obstacleScale=None, forceDistance=None)[source]#

Parameters required to create an Agent in the Social Force Model.

See the scientific publication for more details about this model https://doi.org/10.1038/35035023

position#: Position of the agent.

orientation#: Orientation of the agent.

journey_id#: Id of the journey the agent follows.

stage_id#: Id of the stage the agent targets.

velocity#: current velocity of the agent.

mass#: mass of the agent. [in kg] (is called m)

desired_speed#: desired Speed of the agent. [in m/s] (is called v0)

reaction_time#: reaction Time of the agent. [in s] (is called \(\tau\))

agent_scale#: indicates how strong an agent is influenced by pushing forces from neighbors. [in N] (is called A)

obstacle_scale#: indicates how strong an agent is influenced by pushing forces from obstacles. [in N] (is called A)

force_distance#: indicates how much the distance between an agent and obstacles or neighbors influences social forces. [in m] (is called B)

radius#: radius of the space an agent occupies. [in m] (is called r)

property agentScale: float#

agent_scale: float = 2000#

property desiredSpeed: float#

desired_speed: float = 0.8#

property forceDistance: float#

force_distance: float = 0.08#

journey_id: int = -1#

mass: float = 80.0#

property obstacleScale: float#

obstacle_scale: float = 2000#

orientation: tuple[float, float] = (0.0, 0.0)#

position: tuple[float, float] = (0.0, 0.0)#

radius: float = 0.3#

property reactionTime: float#

reaction_time: float = 0.5#

stage_id: int = -1#

velocity: tuple[float, float] = (0.0, 0.0)#

class SocialForceModelState(backing)[source]#

property agentScale: float#

property agent_scale: float#

property desiredSpeed: float#: desired Speed of this agent.

property desired_speed: float#: desired Speed of this agent.

property forceDistance: float#

property force_distance: float#

property mass: float#: mass of this agent.

property obstacleScale: float#

property obstacle_scale: float#

property radius: float#: radius of this agent.

property reactionTime: float#: reaction Time of this agent.

property reaction_time: float#

property velocity: tuple[float, float]#: velocity of this agent.

class SqliteTrajectoryWriter(*, output_file: pathlib.Path, every_nth_frame: int = 4)[source]#

Bases: jupedsim.serialization.TrajectoryWriter

Write trajectory data into a sqlite db

begin_writing(simulation: jupedsim.simulation.Simulation) → None[source]#

Begin writing trajectory data.

This method is intended to handle all data writing that has to be done once before the trajectory data can be written. E.g. Meta information such as framerate etc…

connection() → sqlite3.Connection[source]#

every_nth_frame() → int[source]#

Returns the interval of this writer in frames between writes.

1 indicates all frames are written, 10 indicates every 10th frame is writen and so on.

Returns:: Number of frames between writes as int

write_iteration_state(simulation: jupedsim.simulation.Simulation) → None[source]#

Write trajectory data of one simulation iteration.

This method is intended to handle serialization of the trajectory data of a single iteration.

class TrajectoryWriter[source]#

Interface for trajectory serialization

exception Exception#

Bases: Exception

Represents exceptions specific to the trajectory writer.

abstractmethod begin_writing(simulation) → None[source]#

Begin writing trajectory data.

This method is intended to handle all data writing that has to be done once before the trajectory data can be written. E.g. Meta information such as frame rate etc…

abstractmethod every_nth_frame() → int[source]#

Returns the interval of this writer in frames between writes.

1 indicates all frames are written, 10 indicates every 10th frame is writen and so on.

Returns:: Number of frames between writes as int

abstractmethod write_iteration_state(simulation) → None[source]#

Write trajectory data of one simulation iteration.

This method is intended to handle serialization of the trajectory data of a single iteration.

class Transition(backing)[source]#

Describes the Transition at a stage.

This type describes how a agent will proceed after completing its stage. This effectively describes the set of outbound edges for a stage.

There are 3 types of transitions currently available:

Fixed transitions: On completion of this transitions stage all agents will proceed to the specified next stage.
Round robin transitions: On completion of this transitions stage agents will proceed in a weighted round-robin manner. A round-robin transitions with 3 outgoing stages and the weights 5, 7, 11 the first 5 agents to make a choice will take the first stage, the next 7 the second stage and the next 11 the third stage. Next 5 will take the first stage, and so on…
Least targeted transition: On completion of this stage agents will proceed towards the currently least targeted amongst the specified choices. The number of “targeting” agents is the amount of agents currently moving towards this stage. This includes agents from different journeys.

static create_fixed_transition(stage_id: int) → Transition[source]#

Create a fixed transition.

On completion of this transitions stage all agents will proceed to the specified next stage.

Parameters:: stage_id – id of the stage to move to next.

static create_least_targeted_transition(stage_ids: list[int]) → Transition[source]#

Create a least targeted transition.

On completion of this stage agents will proceed towards the currently least targeted amongst the specified choices. The number of “targeting” agents is the amount of agents currently moving towards this stage. This includes agents from different journeys.

Parameters:: stage_ids – list of stage ids to choose the next target from.

static create_round_robin_transition(stage_weights: list[tuple[int, int]]) → Transition[source]#

Create a round-robin transition.

Round-robin transitions: On completion of this transitions stage agents will proceed in a weighted round-robin manner. A round-robin transitions with 3 outgoing stages and the weights 5, 7, 11 the first 5 agents to make a choice will take the first stage, the next 7 the second stage and the next 11 the third stage. Next 5 will take the first stage, and so on…

Parameters:: stage_weights – list of id/weight tuples.

class WaitingSetStage(backing)[source]#

Models a set of waiting positions that can be activated or deactivated.

Similar as with a NotifiableQueueStage there needs to be a set of waiting positions defined which will be filled in order of definition. The WaitingSetStage now can be active or inactive. If active agents will fill waiting positions until all are occupied. Additional agents will all try to wait at the last defined waiting position. In inactive state the WaitingSetStage acts as a simple waypoint at the position of the first defined waiting position.

count_targeting() → int[source]#

Returns:: Number of agents currently targeting this stage.

count_waiting() → int[source]#

Returns:: Number of agents currently waiting at this stage.

waiting() → list[int][source]#

Access the ids of all waiting agents in order they are waiting.

Returns:: list of waiting agents ordered by their position.

property state: WaitingSetState#

State of the set.

Can be active or inactive, see WaitingSetState

class WaitingSetState(*args, **kwds)[source]#

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access:
```
>>> Color.RED
<Color.RED: 1>
```
value lookup:
```
>>> Color(1)
<Color.RED: 1>
```
name lookup:
```
>>> Color['RED']
<Color.RED: 1>
```

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

ACTIVE#

INACTIVE#

class WaypointStage(backing)[source]#

Models a waypoint.

A waypoint is considered to be reached if an agent is within the specified distance to the waypoint.

count_targeting() → int[source]#: Returns: Number of agents currently targeting this stage.

distribute_by_density(*, polygon: shapely.Polygon, density: float, distance_to_agents: float, distance_to_polygon: float, seed: int | None = None, max_iterations: int = 10000) → list[tuple[float, float]][source]#

Generates randomized 2D coordinates based on a desired agent density per square meter.

This function will generate as many 2D coordinates as required to reach the desired density. Essentially this function tries to place area * density many agents while adhering to the distance_to_polygon and distance_to_agents constraints. This function may not always be able to generate the requested coordinate because it cannot do so without violating the constraints. In this case the function will stop after max_iterations and raise an Exception.

Parameters:

polygon – Area where to generate 2D coordinates in.
density – desired density in agents per square meter
distance_to_agents – minimal distance between the centers of agents
distance_to_polygon – minimal distance between the center of agents and the polygon edges
seed – Will be used to seed the random number generator.
max_iterations – Up to max_iterations are attempts are made to place a random point without constraint violation, default is 10_000

Returns:

2D coordinates

Raises:

AgentNumberError – if not all agents could be placed.
IncorrectParameterError – if polygon is not of type Polygon

distribute_by_number(*, polygon: shapely.Polygon, number_of_agents: int, distance_to_agents: float, distance_to_polygon: float, seed: int | None = None, max_iterations: int = 10000) → list[tuple[float, float]][source]#

Generates specified number of randomized 2D coordinates.

This function will generate the speficied number of 2D coordinates where all coordinates are inside the specified geometry and generated coordinates are constraint by distance_to_agents and distance_to_polygon. This function may not always be able to generate the requested coordinate because it cannot do so without violating the constraints. In this case the function will stop after max_iterations and raise an Exception.

Parameters:

polygon – polygon where the agents shall be placed
number_of_agents – number of agents to be distributed
distance_to_agents – minimal distance between the centers of agents
distance_to_polygon – minimal distance between the center of agents and the polygon edges
seed – Will be used to seed the random number generator.
max_iterations – Up to max_iterations are attempts are made to place a random point without constraint violation, default is 10_000

Returns:

2D coordinates

Raises:

AgentNumberError – if not all agents could be placed.
IncorrectParameterError – if polygon is not of type Polygon

distribute_by_percentage(*, polygon: shapely.Polygon, percent: float, distance_to_agents: float, distance_to_polygon: float, seed: int | None = None, max_iterations: int = 10000, k: int = 30)[source]#

Generates randomized 2D coordinates that fill the specified area to a percentage of a possible maximum.

This function will generate 2D coordinates in the specified area. The number of positions generated depends on the ability to place aditional points. This function may not always be able to generate the requested coordinate because it cannot do so without violating the constraints. In this case the function will stop after max_iterations and raise an Exception.

Parameters:

polygon – polygon where agents can be placed.
percent – percent value of occupancy to generate. needs to be in the intervall (0, 100]
distance_to_agents – minimal distance between the centers of agents
distance_to_polygon – minimal distance between the center of agents and the polygon edges
seed – Will be used to seed the random number generator.
max_iterations – Up to max_iterations are attempts are made to place a random point without constraint violation, default is 10_000
k – maximum number of attempts to place neighbors to already inserted points. A higher value will result in a higher density but will greatly increase runtim.

Returns:

2D coordinates

Raises:

AgentNumberError – if not all agents could be placed.
IncorrectParameterError – if polygon is not of type Polygon

distribute_in_circles_by_density(*, polygon: shapely.Polygon, distance_to_agents: float, distance_to_polygon: float, center_point: tuple[float, float], circle_segment_radii: list[tuple[float, float]], densities: list[float], seed: int | None = None, max_iterations: int = 10000) → list[tuple[float, float]][source]#

Generates randomized 2D coordinates in a user defined number of rings with defined density.

This function will generate 2D coordinates in the intersection of the polygon and the rings specified by the centerpoint and the min/max radii of each ring. The number of positions generated is defined by the desired density and available space of each ring. This function may not always by able to generate the requested coordinate because it cannot do so without violating the constraints. In this case the function will stop after max_iterations and raise an Exception.

Parameters:

polygon – polygon where agents can be placed.
distance_to_agents – minimal distance between the centers of agents
distance_to_polygon – minimal distance between the center of agents and the polygon edges
center_point – Center point of the rings.
circle_segment_radii – min/max radius per ring, rings may not overlap
desnities – density in positionsper square meter for each ring
seed – Will be used to seed the random number generator.
max_iterations – Up to max_iterations are attempts are made to place a random point without constraint violation, default is 10_000

Returns:

2D coordinates

Raises:

AgentNumberError – if not all agents could be placed.
IncorrectParameterError – if polygon is not of type Polygon
OverlappingCirclesError – if rings in circle_segment_radii overlapp

distribute_in_circles_by_number(*, polygon: shapely.Polygon, distance_to_agents: float, distance_to_polygon: float, center_point: tuple[float, float], circle_segment_radii: list[tuple[float, float]], numbers_of_agents: list[int], seed=None, max_iterations=10000) → list[tuple[float, float]][source]#

Generates randomized 2D coordinates in a user defined number of rings.

This function will generate 2D coordinates in the intersection of the polygon and the rings specified by the centerpoint and the min/max radii of each ring. number_of_agents is expected to contain the number of agents to be placed for each ring. This function may not always be able to generate the requested coordinate because it cannot do so without violating the constraints. In this case the function will stop after max_iterations and raise an Exception.

Parameters:

polygon – polygon where agents can be placed.
distance_to_agents – minimal distance between the centers of agents
distance_to_polygon – minimal distance between the center of agents and the polygon edges
center_point – Center point of the rings.
circle_segment_radii – min/max radius per ring, rings may not overlap
number_of_agents – agents to be placed per ring
seed – Will be used to seed the random number generator.
max_iterations – Up to max_iterations are attempts are made to place a random point without constraint violation, default is 10_000

Returns:

2D coordinates

Raises:

AgentNumberError – if not all agents could be placed.
IncorrectParameterError – if polygon is not of type Polygon
OverlappingCirclesError – if rings in circle_segment_radii overlapp

distribute_until_filled(*, polygon: shapely.Polygon, distance_to_agents: float, distance_to_polygon: float, seed: int | None = None, max_iterations: int = 10000, k: int = 30) → list[tuple[float, float]][source]#

Generates randomized 2D coordinates that fill the specified area.

Parameters:

polygon – polygon where agents can be placed.
distance_to_agents – minimal distance between the centers of agents
distance_to_polygon – minimal distance between the center of agents and the polygon edges
seed – Will be used to seed the random number generator.
max_iterations – Up to max_iterations are attempts are made to place a random point without constraint violation, default is 10_000
k – maximum number of attempts to place neighbors to already inserted points. A higher value will result in a higher density but will greatly increase runtim.

Returns:

2D coordinates

Raises:

AgentNumberError – if not all agents could be placed.
IncorrectParameterError – if polygon is not of type Polygon

get_build_info() → BuildInfo[source]#

Get build information about jupedsim.

The received BuildInfo is printable, e.g.

print(get_build_info())

This will display a human-readable string stating basic information about this library.

set_debug_callback(fn: Callable[[str], None]) → None[source]#

Set receiver for debug messages.

Parameters:: fn (fn<str>) – function that accepts a msg as string

set_error_callback(fn: Callable[[str], None]) → None[source]#

Set receiver for error messages.

Parameters:: fn (fn<str>) – function that accepts a msg as string

set_info_callback(fn: Callable[[str], None]) → None[source]#

Set receiver for info messages.

Parameters:: fn (fn<str>) – function that accepts a msg as string

set_warning_callback(fn: Callable[[str], None]) → None[source]#

Set receiver for warning messages.

Parameters:: fn (fn<str>) – function that accepts a msg as string

jupedsim

Contents

jupedsim#

Package Contents#

Classes#

Functions#

Attributes#

`jupedsim`#