DOCSEARCHbyAlgolia
Submit Docs

HighwayEnv Documentation

repository·main·Indexed 25 days ago

https://github.com/farama-foundation/highwayenv

A collection of environments for simulated highway driving and tactical decision-making tasks, compatible with the Gymnasium API. It provides 10 driving scenario families, including highway, intersection, exit, lane-keeping, merge, parking, racetrack, roundabout, two-way, and u-turn. The library supports various action types (Continuous, Discrete, and DiscreteMetaAction), manual control simulation, and integration with RL libraries such as Stable Baselines3 and rl-agents.

Tokens
25.2K
Snippets
56
Records
133
Agent score
85%

What's inside HighwayEnv

  1. Overview of HighwayEnv environments

    main

    HighwayEnv provides ten distinct environments for autonomous driving decision-making. All environments follow the Gymnasium API and feature configurable observations, actions, dynamics, and rewards.

    Available environments include:

    EnvironmentDescriptionAction type
    HighwayDrive fast on a multilane highway while avoiding collisions.Discrete
    MergeMerge onto a highway from an on-ramp through dense traffic.Discrete
    RoundaboutNavigate a roundabout with merging and exiting traffic.Discrete
    ParkingPark in a given space with the correct heading (goal-conditioned).Continuous
    IntersectionCross an unsignalized intersection among other vehicles.Discrete
    RacetrackFollow a racetrack as fast as possible while staying on the road.Continuous
    Lane KeepingSteer to follow a sine-wave lane using bicycle dynamics.Continuous
    Two WayOvertake on a two-way road with oncoming traffic (risk management).Discrete
    ExitNavigate across lanes to reach a highway exit ramp.Discrete
    U-TurnOvertake blocking vehicles through a double-lane U-turn.Discrete

  3. Understand the Kinematic Bicycle Model in highway-env

    main

    The vehicle kinematics in highway-env are implemented using the Kinematic Bicycle Model. This model calculates the vehicle's state transitions based on forward speed, heading, acceleration, and steering commands.

    State variables include:

    • $(x, y)$: Vehicle position
    • $v$: Forward speed
    • $\psi$: Heading
    • $a$: Acceleration command
    • $\beta$: Slip angle at the center of gravity
    • $\delta$: Front wheel angle (steering command)

    These kinematic calculations are performed internally during the Vehicle.step method call.

  4. Available driving scenario environments

    main

    HighwayEnv provides 10 driving scenario families. Many of these offer variants such as fast, continuous-control, connected-lane, multi-agent, generic, large, or oval. The families are:

    • highway
    • intersection
    • exit
    • lane-keeping
    • merge
    • parking
    • racetrack
    • roundabout
    • two-way
    • u-turn

  5. Understand HighwayEnv dynamics

    main

    The dynamics of a highway-env environment are determined by two primary components: the description of the Roads and the Vehicles (including their physics and behavioral models).

    • Roads: Defined by a RoadNetwork and a list of Vehicle objects. The road structure dictates the available paths and constraints.
    • Vehicles: Defined by their kinematics (physics), controllers (how they act), and behavior (how they react to surroundings).

  6. Quickstart with HighwayEnv

    main

    HighwayEnv provides Gymnasium-compatible environments for autonomous driving tasks like highway cruising, merging, and intersection crossing. To use it, register the environments using gym.register_envs(highway_env), initialize an environment with gym.make(), and follow the standard Gymnasium loop: reset(), step(action), and handling terminated or truncated flags.

    import gymnasium as gym
import highway_env

gym.register_envs(highway_env)

# Initialise the environment
env = gym.make("highway-v0", config={"lanes_count": 3}, render_mode="human")

# Reset the environment to generate the first observation
obs, info = env.reset()
for _ in range(1000):
    # this is where you would insert your policy
    action = env.action_space.sample()

    # step (transition) through the environment with the action
    # receiving the next observation, reward, and if the episode has terminated or truncated
    obs, reward, terminated, truncated, info = env.step(action)

    # If the episode has ended then we can reset to start a new episode
    if terminated or truncated:
        obs, info = env.reset()

env.close()

  7. Use the Merge environment

    main

    The Merge environment simulates an ego-vehicle on a highway approaching a road junction with an access ramp. The agent's goal is to maintain high speed while allowing incoming vehicles from the ramp to merge safely into traffic.

    You can instantiate the environment using gym.make() with one of the following IDs:

  8. Set up a development environment for HighwayEnv

    main

    For contributors, the following tools are recommended:

    • uv: A fast Python package manager with lockfile support. Install via pip install uv or the standalone installer.
    • just: A command runner used for common development tasks (refer to the Justfile in the repository).

  9. Configure an environment via the config dictionary

    main

    The observations, actions, dynamics, and rewards of an environment are parameterized by a configuration dictionary accessible via the env.unwrapped.config attribute. You can pass this configuration during environment creation using the config argument in gymnasium.make.

    import gymnasium
import highway_env

# Example: changing the number of lanes via config
env = gymnasium.make(
    "highway-v0",
    config={"lanes_count": 2},
    render_mode='rgb_array',
)
env.reset()

# Access the configuration after creation
print(env.unwrapped.config)

  10. Install Ubuntu dependencies for pygame-ce

    main

    If you are using Linux (Ubuntu), you may need to install additional system dependencies to support pygame-ce for graphics rendering.

    sudo apt-get update -y
sudo apt-get install -y python-dev libsdl-image1.2-dev libsdl-mixer1.2-dev \
    libsdl-ttf2.0-dev libsdl1.2-dev libsmpeg-dev python-numpy subversion libportmidi-dev \
    ffmpeg libswscale-dev libavformat-dev libavcodec-dev libfreetype6-dev gcc

  11. Train Highway environments with Stable Baselines3

    main

    You can train reinforcement learning agents for highway-v0 using the Stable Baselines3 library. Available examples include:

    • DQN: Standard Deep Q-Network training.
    • PPO: Proximal Policy Optimization training.
    • DQN with CNN: Training using image observations and a CNN model architecture.
    • Parking with HER: Training a goal-conditioned parking-v0 policy using Hindsight Experience Replay (HER).
    WARNING

    Stable Baselines3 does not currently support gymnasium. These examples are compatible with older versions of highway-env (e.g., highway-env==1.5).