FLUIDS Core API

Simulator Interface

The most powerful way to interact with fluids is to create a fluids.FluidSim object. This object creates the environment, sets up all cars, and pedestrians, and controls background objects in the scene. The initialization arguments to this object control the parameters of the generated environment. A fluids.State object controls the layout of the scene.

class fluids.FluidSim(visualization_level=1, fps=30, obs_space='fluids_obs_none', obs_args={}, background_control='fluids_background_null', reward_fn='fluids_reward_path', screen_dim=800)

This class controls the generation and simulation of the urban environment.

Parameters:

• state (str) – Name of json layout file specifiying environment object positions. Default is “fluids_state_city”
• visualization_level (int) – 0 is no visualization. Higher numbers turn on more debug visuals.
• controlled_cars (int) – Number of cars to accept external control for
• background_cars (int) – Number of cars to control with the background planner
• background_peds (int) – Number of pedestrians to control with the background planner
• fps (int) – If set to a positive number, caps the FPS of the simulator. If set to 0, FPS is unbound. Default is 30
• obs_space (str) – Controls what observation representation to return for controlled cars. fluids.BIRDSEYE or fluids.NONE
• screen_dim (int) – Height of the visualization screen. Default is 800

get_control_keys()

Returns:Keys for every controlled car in the scene Return type:list of keys

get_observations(keys={})

Get observations from controlled cars in the scene.

Parameters:keys (dict of keys) – Keys should refer to cars in the scene Returns:Dictionary mapping keys of controlled cars to FluidsObs object Return type:dict of (key -> FluidsObs)

get_supervisor_actions(action_type=<class 'fluids.actions.SteeringAccAction'>, keys={})

Get the actions assigned to the selected car by the FLUIDS multiagent planer

Parameters:

• action_type (fluids.Action) – Type of action to return. VelocityAction, SteeringAccAction, and SteeringAction are currently supported
• keys (set) – Set of keys for controlled cars or background cars to return actions for

Returns:

Dictionary mapping car keys to actions

Return type:

dict of (key -> fluids.Action)

set_state(state)

Sets the state to simulate

Parameters:state (fluids.State) – State object to simulate

step(actions={})

Simulates one frame

Parameters:actions (dict of (key -> action)) – Keys in dict should correspond to controlled cars. Action can be of type KeyboardAction, SteeringAction, SteeringAccAction, or VelocityAction

class fluids.State(layout='fluids_state_city', controlled_cars=0, background_cars=0, background_peds=0, use_traffic_lights=True, use_ped_lights=True, vis_level=1)

This class represents the state of the world

Parameters:

• layout (str) – Name of json layout file specifiying environment object positions. Default is “fluids_state_city”
• controlled_cars (int) – Number of cars to accept external control for
• background_cars (int) – Number of cars to control with the background planner
• background_peds (int) – Number of pedestrians to control with the background planner
• use_traffic_lights (bool) – Sets whether traffic lights are generated
• use_ped_lights (bool) – Sets whether pedestrian lights are generated

Action Types

FLUIDS supports four action types. All action types are acceptable for FluidSim.step.

class fluids.actions.KeyboardAction

This action passes control to keyboard input

class fluids.actions.SteeringAction(steer)

This action provides a steering control. The supervisor will control the acceleration

Parameters:steer (float in range (-1, 1)) –

class fluids.actions.SteeringAccAction(steer, acc)

This action provides both steering and acceleration control.

Parameters:

• steer (float in range (-1, 1)) –
• acc (float in range (-1, 1)) –

class fluids.actions.VelocityAction(vel)

This action provides a target velocity for the car to track

Parameters:vel (float in range (0, 1)) –

class fluids.actions.LastValidAction

This action causes car to replay its last valid action. This is useful when testing coarse planning methods.

Observation Types

FLUIDS supports two observation types currently, a BirdsEye observation and a Grid observation.

class fluids.obs.FluidsObs

The base FLUIDS observation interface

get_array()

Returns a numpy array representation of the observation

Returns: Return type:np.array

class fluids.obs.GridObservation(car, obs_dim=500, shape=(500, 500))

Grid observation type. Observation is an occupancy grid over the detection region. Observation has 9 dimensions: terrain, drivable regions, illegal drivable regions, cars, pedestrians, traffic lights, way points, point trajectory and edge trajectory. Array representation is (grid_size, grid_size, 9)

class fluids.obs.BirdsEyeObservation(car, obs_dim=500)

Bird’s-eye 2D top-down image centered on the vehicle, similar to what is visualized. Minor difference is that drivable regions are colorless to differentiate from illegal drivable regions. Array representation is (obs_dim, obs_dim, 3).

Command Line Interface

FLUIDS also provides a command line interface for visualizing the environment running without a user agent. Controlled agents in this mode are controllable by keyboard only.

python3 -m fluids

Run with -h flag to see arguments

>>> python3 -m fluids -h
usage: __main__.py [-h] [-b N] [-c N] [-p N] [-v N] [-o str] [--state file]

FLUIDS First Order Lightweight Urban Intersection Driving Simulator

optional arguments:
-h, --help    show this help message and exit
-b N          Number of background cars
-c N          Number of controlled cars
-p N          Number of background pedestrians
-v N          Visualization level
-o str        Observation type
--state file  Layout file for state generation

Keyboard commands for when visualizer is running:
 .            Increases debug visualization
 ,            Decreases debug visualization
 o            Switches observation type