jupedsim#

Package Contents#

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.

Do not use.

Retrieve agents from the simulation.

property id: int#

Numeric id of the agent in this simulation.

Return type:

int

property journey_id: int#

Id of the JourneyDescription the agent is currently following.

Return type:

int

property stage_id: int#

Id of the Stage the Agent is currently targeting.

Return type:

int

property position: tuple[float, float]#

Position of the agent.

Return type:

tuple[float, float]

property orientation: tuple[float, float]#

Orientation of the agent.

Return type:

tuple[float, float]

property model: jupedsim.models.GeneralizedCentrifugalForceModelState | jupedsim.models.CollisionFreeSpeedModelState#

Access model specific state of this agent.

Return type:

jupedsim.models.GeneralizedCentrifugalForceModelState | jupedsim.models.CollisionFreeSpeedModelState

exception AgentNumberError(message)[source]#

Bases: Exception

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception IncorrectParameterError(message)[source]#

Bases: Exception

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception NegativeValueError(message)[source]#

Bases: Exception

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception OverlappingCirclesError(message)[source]#

Bases: Exception

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

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 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 (shapely.Polygon) – Area where to generate 2D coordinates in.

  • density (float) – desired density in agents per square meter

  • distance_to_agents (float) – minimal distance between the centers of agents

  • distance_to_polygon (float) – minimal distance between the center of agents and the polygon edges

  • seed (int | None) – Will be used to seed the random number generator.

  • max_iterations (int) – Up to max_iterations are attempts are made to place a random point without constraint violation, default is 10_000

Returns:

2D coordiantes

Raises:
Return type:

list[tuple[float, float]]

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 coordiantes.

This function will generate the speficied number of 2D coordiantes where all coordiantes are inside the specified geometry and generated coordinates are constraint by distance_to_agents and distance_to_polygon. 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 (shapely.Polygon) – polygon where the agents shall be placed

  • number_of_agents (int) – number of agents to be distributed

  • distance_to_agents (float) – minimal distance between the centers of agents

  • distance_to_polygon (float) – minimal distance between the center of agents and the polygon edges

  • seed (int | None) – Will be used to seed the random number generator.

  • max_iterations (int) – Up to max_iterations are attempts are made to place a random point without conastraint violation, default is 10_000

Returns:

2D coordiantes

Raises:
Return type:

list[tuple[float, float]]

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 coordiantes 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 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 (shapely.Polygon) – polygon where agents can be placed.

  • percent (float) – percent value of occupancy to generate. needs to be in the intervall (0, 100]

  • distance_to_agents (float) – minimal distance between the centers of agents

  • distance_to_polygon (float) – minimal distance between the center of agents and the polygon edges

  • seed (int | None) – Will be used to seed the random number generator.

  • max_iterations (int) – Up to max_iterations are attempts are made to place a random point without conastraint violation, default is 10_000

  • k (int) – 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 coordiantes

Raises:
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 coordiantes 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 (shapely.Polygon) – polygon where agents can be placed.

  • distance_to_agents (float) – minimal distance between the centers of agents

  • distance_to_polygon (float) – minimal distance between the center of agents and the polygon edges

  • center_point (tuple[float, float]) – Center point of the rings.

  • circle_segment_radii (list[tuple[float, float]]) – min/max radius per ring, rings may not overlap

  • desnities – density in positionsper square meter for each ring

  • seed (int | None) – Will be used to seed the random number generator.

  • max_iterations (int) – Up to max_iterations are attempts are made to place a random point without conastraint violation, default is 10_000

  • densities (list[float]) –

Returns:

2D coordiantes

Raises:
Return type:

list[tuple[float, float]]

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 coordiantes 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 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 (shapely.Polygon) – polygon where agents can be placed.

  • distance_to_agents (float) – minimal distance between the centers of agents

  • distance_to_polygon (float) – minimal distance between the center of agents and the polygon edges

  • center_point (tuple[float, float]) – Center point of the rings.

  • circle_segment_radii (list[tuple[float, float]]) – 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 conastraint violation, default is 10_000

  • numbers_of_agents (list[int]) –

Returns:

2D coordiantes

Raises:
Return type:

list[tuple[float, float]]

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 coordiantes that fill the specified area.

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 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 (shapely.Polygon) – polygon where agents can be placed.

  • distance_to_agents (float) – minimal distance between the centers of agents

  • distance_to_polygon (float) – minimal distance between the center of agents and the polygon edges

  • seed (int | None) – Will be used to seed the random number generator.

  • max_iterations (int) – Up to max_iterations are attempts are made to place a random point without conastraint violation, default is 10_000

  • k (int) – 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 coordiantes

Raises:
Return type:

list[tuple[float, float]]

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()
Parameters:

obj (jupedsim.native.Geometry) –

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

Access the boundary polygon of the walkable area.

Returns:

List of 2d points describing the polygon.

Return type:

list[tuple[float, float]]

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.

Return type:

list[list[tuple[float, float]]]

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.

Create a Journey Description.

Parameters:

stage_ids (Optional[list[int]]) – list of stages this journey should contain.

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

Add additional stage or stages.

Parameters:

stages (int | list[int]) – A single stage id or a list of stage ids.

Return type:

None

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 (int) – id of the stage to set the transition for.

  • transition (Transition) – transition to set

Return type:

None

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 (int) – id of the stage to move to next.

Return type:

Transition

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[tuple[int, int]]) – list of id/weight tuples.

Return type:

Transition

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[int]) – list of stage ids to choose the next target from.

Return type:

Transition

class BuildInfo[source]#
property git_commit_hash: str#

SHA1 commit hash of this version.

Returns:

SHA1 of this version.

Return type:

str

property git_commit_date: str#

Date this commit was created.

Returns:

Date the commit of this version as string.

Return type:

str

property git_branch: str#

Branch this commit was crated from.

Returns:

name of the branch this version was build from.

Return type:

str

property compiler: str#

Compiler the native code was compiled with.

Returns:

Compiler identification.

Return type:

str

property compiler_version: str#

Compiler version the native code was compiled with.

Returns:

Compiler version number.

Return type:

str

property library_version: str#
Return type:

str

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.

Return type:

BuildInfo

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

Return type:

None

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

Return type:

None

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

Return type:

None

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

Return type:

None

class CollisionFreeSpeedModel[source]#

Parameters for Collision Free Speed Model

All attributes are initialized with reasonably good defaults.

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

strength_neighbor_repulsion: float = 8.0#
range_neighbor_repulsion: float = 0.1#
strength_geometry_repulsion: float = 5.0#
range_geometry_repulsion: float = 0.02#
class CollisionFreeSpeedModelAgentParameters[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(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.

v0#

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.

position: tuple[float, float] = (0.0, 0.0)#
time_gap: float = 1.0#
v0: float = 1.2#
radius: float = 0.2#
journey_id: int = 0#
stage_id: int = 0#
as_native() → jupedsim.native.CollisionFreeSpeedModelAgentParameters[source]#
Return type:

jupedsim.native.CollisionFreeSpeedModelAgentParameters

class CollisionFreeSpeedModelState(backing)[source]#
property time_gap: float#
Return type:

float

property v0: float#

Maximum speed of this agent.

Return type:

float

property radius: float#

Radius of this agent.

Return type:

float

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)

strength_neighbor_repulsion: float = 0.3#
strength_geometry_repulsion: float = 0.2#
max_neighbor_interaction_distance: float = 2#
max_geometry_interaction_distance: float = 2#
max_neighbor_interpolation_distance: float = 0.1#
max_geometry_interpolation_distance: float = 0.1#
max_neighbor_repulsion_force: float = 3#
max_geometry_repulsion_force: float = 3#
class GeneralizedCentrifugalForceModelAgentParameters[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.

e0#

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

v0#

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.

speed: float = 0.0#
e0: tuple[float, float] = (0.0, 0.0)#
position: tuple[float, float] = (0.0, 0.0)#
orientation: tuple[float, float] = (0.0, 0.0)#
journey_id: int#
stage_id: int#
mass: float = 1#
tau: float = 0.5#
v0: float = 1.2#
a_v: float = 1#
a_min: float = 0.2#
b_min: float = 0.2#
b_max: float = 0.4#
as_native() → jupedsim.native.GeneralizedCentrifugalForceModelAgentParameters[source]#
Return type:

jupedsim.native.GeneralizedCentrifugalForceModelAgentParameters

class GeneralizedCentrifugalForceModelState(backing)[source]#
property speed: float#

Speed of this agent.

Return type:

float

property e0: tuple[float, float]#

Desired direction of this agent.

Return type:

tuple[float, float]

property tau: float#
Return type:

float

property v0: float#

Maximum speed of this agent.

Return type:

float

property a_v: float#

Stretch of the ellipsis semi-axis along the movement vector.

Return type:

float

property a_min: float#

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

Return type:

float

property b_min: float#

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

Return type:

float

property b_max: float#

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

Return type:

float

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

db_connection_str (str) –

property num_frames: int#

Access the number of frames stored in this recording.

Returns:

Number of frames in this recording.

Return type:

int

property fps: float#

How many frames are stored per second.

Returns:

Frames per second of this recording.

Return type:

float

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.

Return type:

RecordingFrame

geometry() → shapely.GeometryCollection[source]#

Access this recordings’ geometry.

Returns:

walkable area of the simulation that created this recording.

Return type:

shapely.GeometryCollection

bounds() → jupedsim.internal.aabb.AABB[source]#

Get bounds of the position data contained in this recording.

Return type:

jupedsim.internal.aabb.AABB

class RecordingAgent[source]#

Data for a single agent at a single frame.

id: int#
position: tuple[float, float]#
orientation: tuple[float, float]#
class RecordingFrame[source]#

A single frame from the simulation.

index: int#
agents: list[RecordingAgent]#
class RoutingEngine(geometry: str | shapely.GeometryCollection | shapely.Polygon | shapely.MultiPolygon | shapely.MultiPoint | list[tuple[float, float]], **kwargs: Any)[source]#

RoutingEngine to compute the shortest paths with navigation meshes.

Parameters:
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 (tuple[float, float]) – point from which to find the shortest path

  • to (tuple[float, float]) – 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.

Return type:

list[tuple[float, float]]

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.

Parameters:

p (tuple[float, float]) –

Return type:

bool

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

Access the navigation mesh geometry.

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

Returns:

The triangles composing the navigation mesh. Each triangle is encoded as 3-tuple of points.

Return type:

list[tuple[tuple[float, float], tuple[float, float], tuple[float, float]]]

edges_for(vertex_id: int)[source]#
Parameters:

vertex_id (int) –

class TrajectoryWriter[source]#

Interface for trajectory serialization

abstract 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…

Return type:

None

abstract 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.

Return type:

None

abstract 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

Return type:

int

class Simulation(*, model: jupedsim.models.CollisionFreeSpeedModel | jupedsim.models.GeneralizedCentrifugalForceModel, 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.

Creates a Simulation.

Parameters:
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[source]#

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[source]#

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[source]#
Parameters:

positions (list[tuple[float, float]]) –

Return type:

int

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

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_journey(journey: jupedsim.journey.JourneyDescription) → int[source]#
Parameters:

journey (jupedsim.journey.JourneyDescription) –

Return type:

int

add_agent(parameters: jupedsim.models.GeneralizedCentrifugalForceModelAgentParameters | jupedsim.models.CollisionFreeSpeedModelAgentParameters) → int[source]#
Parameters:

parameters (jupedsim.models.GeneralizedCentrifugalForceModelAgentParameters | jupedsim.models.CollisionFreeSpeedModelAgentParameters) –

Return type:

int

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 (int) – Id of the agent marked for removal

Returns:

marking for removal was successful

Return type:

bool

removed_agents() → list[int][source]#
Return type:

list[int]

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

count (int) –

Return type:

None

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

  • agent_id (int) –

  • journey_id (int) –

  • stage_id (int) –

Return type:

None

agent_count() → int[source]#
Return type:

int

elapsed_time() → float[source]#
Return type:

float

delta_time() → float[source]#
Return type:

float

iteration_count() → int[source]#
Return type:

int

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

Iterable[jupedsim.agent.Agent]

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

jupedsim.agent.Agent

agents_in_range(pos: tuple[float, float], distance: float) → list[jupedsim.agent.Agent][source]#
Parameters:
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][source]#

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)[source]#
Parameters:

stage_id (int) –

set_tracing(status: bool) → None[source]#
Parameters:

status (bool) –

Return type:

None

get_last_trace() → jupedsim.tracing.Trace[source]#
Return type:

jupedsim.tracing.Trace

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

jupedsim.geometry.Geometry

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

Bases: jupedsim.serialization.TrajectoryWriter

Write trajectory data into a sqlite db

SqliteTrajectoryWriter constructor

Parameters:

  • output_file (pathlib.Path) – pathlib.Path name of the output file. Note: the file will not be written until the first call to ‘begin_writing’

  • every_nth_frame (int) – int indicates interval between writes, 1 means every frame, 5 every 5th

Returns:

SqliteTrajectoryWriter

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…

Parameters:

simulation (jupedsim.simulation.Simulation) –

Return type:

None

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.

Parameters:

simulation (jupedsim.simulation.Simulation) –

Return type:

None

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

Return type:

int

connection() → sqlite3.Connection[source]#
Return type:

sqlite3.Connection

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 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_targeting() → int[source]#
Returns:

Number of agents currently targeting this stage.

Return type:

int

count_enqueued() → int[source]#
Returns:

Number of agents currently enqueued at this stage.

Return type:

int

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

Return type:

None

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.

Return type:

list[int]

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.

property state: WaitingSetState#

State of the set.

Can be active or inactive, see WaitingSetState

Return type:

WaitingSetState

count_targeting() → int[source]#
Returns:

Number of agents currently targeting this stage.

Return type:

int

count_waiting() → int[source]#
Returns:

Number of agents currently waiting at this stage.

Return type:

int

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.

Return type:

list[int]

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.

Return type:

int

class Trace[source]#
property iteration_duration: float#

Time for one simulation iteration in us.

Returns:

Time for one simulation iteration in us

Return type:

float

property operational_level_duration: float#

Time for one simulation iteration in the operational level in us.

Returns:

Time for one simulation iteration in the operational level in us

Return type:

float