jupedsim

`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 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.
Return type:: tuple[float, float]

property model: jupedsim.models.generalized_centrifugal_force.GeneralizedCentrifugalForceModelState | jupedsim.models.collision_free_speed.CollisionFreeSpeedModelState | jupedsim.models.social_force.SocialForceModelState#

Access model specific state of this agent.

Return type:: jupedsim.models.generalized_centrifugal_force.GeneralizedCentrifugalForceModelState | jupedsim.models.collision_free_speed.CollisionFreeSpeedModelState | jupedsim.models.social_force.SocialForceModelState

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 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 (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 coordinates

Raises:

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

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

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 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 (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 constraint 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 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 (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 constraint violation, default is 10_000
densities (list[float]) –

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

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 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 (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 constraint violation, default is 10_000
numbers_of_agents (list[int]) –

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

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

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 constraint 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 coordinates

Raises:

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

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]]]

as_wkt() → str[source]#

_summary_

Returns:: _description_
Return type:: String

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

geometry_id_for_frame(frame_id) → int[source]#

Return type:: int

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

RoutingEngine to compute the shortest paths with navigation meshes.

Parameters:

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

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() → 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]]]
Return type:: tuple[list[tuple[float, float]], list[list[int]]]

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

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

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 an exit stage to the simulation.

Parameters:

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[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.
Return type:: int

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

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

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

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

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

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

Number of agents in the simulation.

Returns:: Number of agents in the simulation.
Return type:: int

elapsed_time() → float[source]#

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

Time step length in seconds of one iteration.

Returns:: Time step length of one iteration.
Return type:: float

iteration_count() → int[source]#

Number of iterations performed since start of the simulation.

Returns:: Number of iterations performed.
Return type:: int

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

Agents in the simulation.

Returns:: Iterator over all agents in the simulation.
Return type:: Iterable[jupedsim.agent.Agent]

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
Return type:: jupedsim.agent.Agent

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

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]

Return all agents inside the given polygon.

Parameters:

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

Specific stage in the simulation.

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

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

Current geometry of the simulation.

Returns:: The geometry of the simulation.
Return type:: jupedsim.geometry.Geometry

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 (jupedsim.geometry.Geometry) – The new geometry to be used in the simulation.
Return type:: None

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

jupedsim

Contents

jupedsim#

Package Contents#

`jupedsim`#