Gym Environment

GKEnv is the main Gymnasium environment class, implementing the F1/10th vehicle simulation with realistic dynamics.

Source: gymkhana/envs/gymkhana_env.py

Creating an environment

import gymnasium as gym
from gymkhana.envs.gymkhana_env import GKEnv

env = gym.make('gymkhana:gymkhana-v0', config={
    'map': 'Spielberg',
    'num_agents': 1,
    'model': 'std',
    'control_input': ['accl', 'steering_angle'],
    'params': GKEnv.f1tenth_std_vehicle_params(),
    'render_mode': 'human',
})

See Configuration for the full list of config options.

Vehicle parameter methods

GKEnv.f1tenth_std_vehicle_params()

Returns the default parameter dictionary for the 1/10 scale F1TENTH car with the STD (single-track drift) model. Includes PAC2002 tire parameters adjusted from a full-scale car.

GKEnv.f1tenth_std_drift_bias_params()

Returns drift-biased parameters for more aggressive drifting behavior.

Step and reset

env.step(action)

Steps the simulation. Returns (obs, reward, terminated, truncated, info).

  • action: ndarray of shape (num_agents, 2) where each row is [steering, longitudinal] — see Action System for control input types

env.reset(options=None)

Resets the environment. Returns (obs, info).

  • options: optional dict with "poses" or "states" keys (see Configuration)

env.update_params(params_dict, index=None)

Update vehicle parameters. If index is specified, updates only that vehicle; otherwise updates all vehicles.

API reference

class gymkhana.envs.gymkhana_env.GKEnv(config: dict = None, render_mode=None, **kwargs)

Gymnasium environment for Gym-Khana autonomous racing.

Implements the standard Gymnasium Env interface. Create via:

env = gym.make('gymkhana:gymkhana-v0', config={...})

Configuration is passed as a dict to __init__ and merged with defaults from default_config(). See that method for all available keys and their defaults. Vehicle physics parameters are documented in gymkhana.envs.dynamic_models; preset parameter dicts are available via f1tenth_vehicle_params(), f1tenth_std_vehicle_params(), etc.

Parameters:

  • config –

    Configuration dict merged with default_config(). Key configuration options:

    • map (str): Track name (default "Spielberg").

    • params (dict): Vehicle parameters (default F1TENTH ST params).

    • model (str): Dynamics model — "ks", "st", "mb", "std" (default "st").

    • num_agents (int): Number of agents (default 2).

    • timestep (float): Physics timestep in seconds (default 0.01).

    • ego_idx (int): Index of the ego agent (default 0).

    • control_input (list): Action types, e.g. ["speed", "steering_angle"].

    • observation_config (dict): Observation type config, e.g. {"type": "drift"}.

    • normalize_obs (bool | None): Observation normalisation; None = auto.

    • normalize_act (bool): Action normalisation (default True).

    • training_mode (str): "race" or "recover" (default "race").

    • predictive_collision (bool): TTC-based (True) or Frenet-based (False) collision.

  • render_mode – Gymnasium render mode ("human", "human_fast", "rgb_array").

metadata = {'render_fps': 100, 'render_modes': ['human', 'human_fast', 'rgb_array']}
classmethod fullscale_vehicle_params() → dict

Return full-scale vehicle parameters from CommonRoad.

Copied as-is from commonroad-vehicle-models/PYTHON/vehiclemodels/parameters/parameters_vehicle1.yaml.

Returns:

Complete parameter dictionary for a full-scale vehicle (ST/MB/STD models).

classmethod f1fifth_vehicle_params() → dict

Return default parameters for the 1/5th scale F1FIFTH car (ST model).

Returns:

Parameter dictionary for ST/KS models.

classmethod f1tenth_vehicle_params() → dict

Return default parameters for the 1/10th scale F1TENTH car (ST model).

Returns:

Parameter dictionary for ST/KS models.

classmethod f1tenth_std_drift_bias_params() → dict

Return STD model parameters tuned for increased drift tendency.

Extends f1tenth_std_vehicle_params() with adjusted CoG, reduced a_max, softer lateral tyre stiffness, and rear-wheel-drive torque split.

Returns:

Parameter dictionary for the STD model with drift bias.

classmethod f1tenth_std_vehicle_params() → dict

Return default parameters for the 1/10th scale F1TENTH car (STD model).

Extends the standard F1TENTH parameters with wheel dynamics (R_w, I_y_w) and the full PAC2002 (Pacejka Magic Formula) tyre coefficient set, adapted from full-scale values. See inline comments for derivation notes.

Returns:

Complete parameter dictionary for the STD model.

classmethod default_config() → dict

Return the default environment configuration dict.

All keys can be overridden by passing a partial config dict to __init__ or by calling configure().

Returns:

Complete default configuration dict.

configure(config: dict) → None

Merge a partial config dict into the current configuration.

Also updates the simulator and action space if they are already initialised (i.e. when called after __init__).

Parameters:

config – Partial configuration dict; keys are merged via deep update.

set_recovery_ranges(v_range, beta_range, r_range, yaw_range)

Set recovery initial state sampling ranges (used by curriculum learning).

step(action, skip_integration=False)

Step the environment by one timestep.

Parameters:

  • action – Control inputs for all agents, shape (num_agents, 2). Each row is [steer, longitudinal].

  • skip_integration – If True, skip dynamics integration (used during reset to generate an initial observation).

Returns:

Tuple (obs, reward, terminated, truncated, info).

reset(seed=None, options=None)

Reset the environment and return an initial observation.

Parameters:

  • seed – Random seed for reproducibility.

  • options –

    Optional dict with one of:

    • "poses": np.ndarray of shape (num_agents, 3) — [x, y, yaw] per agent.

    • "states": np.ndarray of shape (num_agents, 7) — [x, y, delta, v, yaw, yaw_rate, slip_angle] per agent (STD model only).

    Cannot specify both keys simultaneously.

Returns:

Tuple (obs, info).

update_map(map_name: str)

Update the map used by the simulation.

Parameters:

map_name – Name of the map.

update_params(params, index=-1)

Update vehicle parameters for the simulation.

Parameters:

  • params – Dictionary of vehicle parameters.

  • index – If >= 0, update only the specified agent’s params; -1 updates all.

add_render_callback(callback_func)

Add an extra drawing function to call during rendering.

Parameters:

callback_func – Callable with signature (EnvRenderer) -> None invoked each render() call.

render(mode='human')

Render the environment.

Mouse scroll zooms in/out; click-drag pans. Displays agents, map, current FPS, and race information.

Parameters:

mode – Rendering mode — "human" (real-time paced) or "human_fast" (uncapped).

close()

Close the environment and release renderer resources.