symupy.runtime.api package¶

Subpackages¶

symupy.runtime.api.commands package

Submodules¶

symupy.runtime.api.connector module¶

This module details the implementation of a Simulator object in charge of handling the connection between the traffic simulator and this interface. The connection with the traffic simulator is handled by an object called Connector which establishes a messaging protocol with the traffic simulator.

Example

To use the Simulator declare in a string the path to the simulator

>>> from symupy.api import Simulator
>>> path_symuvia = "path/to/libSymuyVia.dylib"
>>> simulator = Simulator(library_path=path_symuvia)

Other parameters can also be send to the simulator in order to provide other configurations:

Example

To send make increase the buffer size to a specific size:

>>> simulator = Simulator(bufferSize = 1000000)

To increase change the flag that traces the flow:

>>> simulator = Simulator(trace_flow = True)

class symupy.runtime.api.connector.Simulator(**kwargs)[source]¶

Bases: symupy.utils.configurator.Configurator, symupy.runtime.logic.runtime.RuntimeDevice

Simulator class for containing object to connect and command a simulation in SymuFlow

Example

Call of the default simulator

>>> from symupy.api import Simulator
>>> simulator = Simulator()

Returns: Symuvia simulator object with simulation parameters
Return type: Simulator

You may also pass suplementary parameters to the object by specifying keys in the call:

Example

To use the Simulator declare in a string the path to the simulator

>>> from symupy.api import Simulator
>>> path_symuvia = "path/to/libSymuyVia.dylib"
>>> simulator = Simulator(library_path=path_symuvia)

This object describes is a configurator manager for the interface between the traffic simulator and the python interface. For more details on the optinal keyword parameters please refer to Configurator class.

Raises

SymupyLoadLibraryError – Error raised whenever the SymuFlow library is not found
SymupyFileLoadError – Error raised whenever the provided path for an scenario cannot be loaded into the Simulator
SymupyVehicleCreationError – Error raised when a vehicle cannot be created
SymupyDriveVehicleError – Error rased when a vehicle state cannot be imposed
NotImplementedError – Not implemented functionality

Returns

Simulator manager object

Return type

Simulator

add_control_probability_zone_mfd(access_probability: dict, minimum_distance: dict)[source]¶

Add a probability to control the access to a specific zone within the network

Parameters

access_probability (dict) – Key (zone name) Value (probability of access)
minimum_distance (dict) – Key (zone name) Value (distance before entering the zone to activate policy)

build_dynamic_param()[source]¶: Construct parameters for vehicle dynamics

create_vehicle(vehtype: str, origin: str, destination: str, lane: int = 1, simid: int = 0) → int[source]¶

Creates a vehicle within the network

Parameters

vehtype (str) – vehicle type according to simulation definitions
origin (str) – network endpoint nodeaccording to simulation
destination (str) – network endpoint nodeaccording to simulation
lane (int) – vehicle lane number, defaults to 1
simid (int) – simulation id, defaults to 0

Returns vehid

Vehicle id of the vehicle created >0

Example

One example to create a vehicle is as follows

>>> with symuflow as s:
>>>     while s.do_next:
>>>         s.request_answer()  # Initialize
>>>         s.request_answer()  # Vehicle 0
>>>         # Vehicle instantiation
>>>         veh_id = s.create_vehicle("VL", "Ext_In", "Ext_Out")
>>>         force_driven = s.request.is_vehicle_driven("1")
>>>         s.request_answer()

create_vehicle_with_route(vehtype: str, origin: str, destination: str, lane: int = 1, creation_time: float = 0, route: str = '') → int[source]¶

Creates a vehicle with a specific route

Parameters

vehtype (str) – vehicle type according to simulation definitions
origin (str) – network endpoint nodeaccording to simulation
destination (str) – network endpoint nodeaccording to simulation
lane (int) – vehicle lane number, defaults to 1
route (str) – route followed by the vehicle, defaults to “”

Return vehid

Vehicle id of the vehicle created >0

property do_next: bool¶

Returns true if the simulation shold continue

Returns: True if next step continues
Return type: bool

drive_vehicle(vehid: int, new_pos: float, destination: Optional[str] = None, lane: str = 1)[source]¶

Drives a vehicle to a specific position

Parameters

vehtype (str, optional) – vehicle type according to simulation definitions
new_pos (float) – position to place the vehicle
destination (str) – link of destination, defaults to None
lane (int) – lane fo destination, defaults to 1
route (str) – route followed by the vehicle, defaults to “”

Example

One example to drive a vehicle as follows

>>> with symuflow as s:
>>>     while s.do_next:
>>>         s.run_step()
>>>         if s.request.is_vehicle_in_network("0"):
>>>             drive_status = s.drive_vehicle(0, 1.0)
>>>             force_driven = s.request.is_vehicle_driven("0")

drive_vehicle_new_route(vehid: int, new_route: str) → int[source]¶

Modifies the current path of a vehicle by stablishing the new route

Parameters

vehid (int) – vehicle id
new_route (str) – string contained links separated by spaces with the path to be taken by the vehicle

Returns

Value containing one of the following values

Value

Description

0

The function is successfully executed

-1

No network loaded

-2

The vehicle doesn’t exist

-3

The new route is empty

-4

A link of the new route not in network

-5

New route is unattainable links are not connected

-6

New route destination is different from original

-7

New route cannot be reached by the vehicle

Return type

int

drive_vehicle_with_control(vehcontrol, vehid: int, destination: Optional[str] = None, lane: str = 1)[source]¶

classmethod from_path(filename_path: str, symuvia_path: str)[source]¶

Alternative constructor for the Simulator

Example

To use this alternative constructor Simulator declare in a string the path to the simulator

>>> path = "path/to/simulator.so"
>>> scenario = "path/to/scenario.xml"
>>> simulator = Simulator.from_path(path,scenario)

get_mfd_speed(sensors_mfd: list = []) → Union[float, tuple][source]¶

Estimates the spatial speed of vehicles in a specific MFD region

Parameters: sensors_mfd (list, optional) – [MFD sensor id, defaults to [].
Returns: Estimated speed computed as ttt/ttd
Return type: TupleFloat

property get_request: dict¶

Returns the query received from the simulator

Returns: Request from the simulator
Return type: dict

get_total_travel_distance(sensors_mfd: list = []) → Union[float, tuple][source]¶

Extracts total travel distance of vehicles in a specific MFD region

Parameters: sensors_mfd (list, optional) – MFD sensor ids, defaults to [].
Returns: Associated total travel distance
Return type: TupleFloat

get_total_travel_time(sensors_mfd: list = []) → Union[float, tuple][source]¶

Extracts the total travel time of vehicles in a specific MFD region

Parameters: sensors_mfd (list, optional) – MFD sensor ids, defaults to [].
Returns: Associated total travel time
Return type: TupleFloat

get_vehicle_abscissa(vehid: int) → float[source]¶

Extract information related to the vehicle’s abscissa

Parameters: vehid (int) – vehicle identifier
Returns: vehicle abcissa (x) position [m]
Return type: float

get_vehicle_acceleration(vehid: int) → float[source]¶

Extract information related to the vehicle’s acceleration

Parameters: vehid (int) – vehicle identifier
Returns: vehicle acceleration [m/s²]
Return type: float

get_vehicle_distance(vehid: int) → float[source]¶

Extract information related to the vehicle’s distance

Parameters: vehid (int) – vehicle identifier
Returns: vehicle distance in link position [m]
Return type: float

get_vehicle_inside_area(sensors_mfd: list = [])[source]¶

Obtains the set of vehicles inside a list

Parameters: sensors_mfd (list, optional) – Sensor name. Defaults to [].
Returns: [description]
Return type: [type]

get_vehicle_lane(vehid: int) → int[source]¶

Extract information related to the vehicle’s lane

Parameters: vehid (int) – vehicle identifier
Returns: vehicle lane position (0) right most lane [int]
Return type: int

get_vehicle_link(vehid: int) → str[source]¶

Extract information related to the vehicle’s link

Parameters: vehid (int) – vehicle identifier
Returns: vehicle link [string]
Return type: str

get_vehicle_ordinate(vehid: int) → float[source]¶

Extract information related to the vehicle’s ordinate

Parameters: vehid (int) – vehicle identifier
Returns: vehicle ordinate (y) position [m]
Return type: float

get_vehicle_speed(vehid: int) → float[source]¶

Extract information related to the vehicle’s speed

Parameters: vehid (int) – vehicle identifier
Returns: vehicle speed [m/s]
Return type: float

get_vehicle_total_travel_distance(vehid: int) → float[source]¶

Extract information related to the vehicle’s total

Parameters: vehid (int) – vehicle identifier
Returns: vehicle total traveled distance [m]
Return type: float

get_vehicle_total_travel_time(vehid: int) → float[source]¶

Extract information related to the vehicle’s total

Parameters: vehid (int) – vehicle identifier
Returns: vehicle total traveled time [s]
Return type: float

init_symbol_states()[source]¶: Initializes symbols before call of a runtime for access in memory

property library¶

load_network() → int[source]¶: Load SymuFlow Simulation File

load_symuvia()[source]¶: Load SymuFlow shared library

modify_control_probability_zone_mfd(access_probability: dict)[source]¶

Modifies a probability to control the access to a specific zone within the network

Parameters: access_probability (dict) – Key (zone name) Value (probability of access)

register_simulation(scenario_path: str)[source]¶: Register simulation file within the simulator

request_answer()[source]¶: Request simulator answer and maps the data locally

run(scenario_path: str = '')[source]¶

Alias method to run simulation

Parameters: scenario_path (Simulation) – Valid simulation scenario

run_simulation(scenario_path: str = '')[source]¶

Run simulation in a single shot

Parameters: sim_object (Simulation) – Valid simulation scenario

run_step(**kwargs)¶

property s_response_dec¶

Obtains instantaneous data from simulator

Returns: last query from simulator
Return type: str

property sampling_time: float¶

Simulation sampling time

Returns: sampling time from XML file
Return type: float

scenarioFilename(encoding=None) → str[source]¶

Scenario filenamme

Returns: Absolute path towards the XML input for SymuFlow
Return type: str

property simulation: symupy.runtime.api.scenario.Simulation¶

Simulation scenario

Returns: Object describing senario under simulation
Return type: Simulation

property simulationstep: float¶

Current simulation step.

Example

You can use the time step to control actions

>>> with simulator as s:
...     while s.do_next()
...         if s.simulationstep>0:
...             print(s.simulationtimestep)

Returns: current simulation iteration
Return type: str

stop_step()[source]¶: Stop current current step of running simulation

symupy.runtime.api.scenario module¶

Scenario Module

This module contains descriptions that stablish a traffic scenario. A traffic scenario is regularly described by a simulation object that points towards properties of the simulator.

class symupy.runtime.api.scenario.Simulation(file_name: str)[source]¶

Bases: object

filename(encoding: Optional[str] = None)[source]¶

This method returns the value of encoding of the simulation scenario under consideration

Parameters: encoding (string, optional) – enconder UTF8, defaults to None
Returns: Full path of scenario
Return type: string

get_links_in_mfd_sensor(sensor_id: str) → tuple[source]¶

Get links associated to a particular MFD sensor for a specific simulation

Parameters: sensor_id (str) – Sensor id
Returns: tuple of strings with links covered by the sensor
Return type: tuple

get_mfd_sensor_names() → tuple[source]¶

Get MFD sensors defined for a specific simulation

Returns: tuple of MFD sensors in the network
Return type: tuple

get_network_endpoints() → tuple[source]¶

Get networks endpoint names

Returns: tuple containing endpoint names
Return type: tuple

get_network_links() → tuple[source]¶

Get network link names

Returns: tuple containing link names
Return type: tuple

get_simulation_parameters() → tuple[source]¶

Get simulation parameters

Returns: tuple with XML dictionary containing parameters
Return type: tuple

get_simulation_steps(simid: int = 0) → range[source]¶

Get simulation steps for an simulation. specify the simulation id via an integer value

Parameters: simid (int, optional) – simulation id , defaults to 0
Returns
Return type: range

get_vehicletype_information() → tuple[source]¶

Get the vehicle parameters

Returns: tuple of dictionaries containing vehicle parameters
Return type: tuple

load_xml_tree() → None[source]¶: Load XML file_name

property time_step¶

property xmltree¶

Module contents¶

Application Programming Interface¶

Contains direct implementations to connect to the traffic simulator.

symupy.runtime package symupy.runtime.api.commands package

Value	Description
0	The function is successfully executed
-1	No network loaded
-2	The vehicle doesn’t exist
-3	The new route is empty
-4	A link of the new route not in network
-5	New route is unattainable links are not connected
-6	New route destination is different from original
-7	New route cannot be reached by the vehicle

v1.0.1

symupy.runtime.api package¶

Subpackages¶

Submodules¶

symupy.runtime.api.connector module¶

symupy.runtime.api.scenario module¶

Module contents¶

Application Programming Interface¶