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 gymkhana/envs/params/f1tenth_std.yaml for values and derivation notes.

Returns:: Complete parameter dictionary for the STD model.

classmethod f1tenth_stp_vehicle_params() → dict

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

Single Track Pacejka: dynamic single-track chassis with a lateral-only Pacejka Magic Formula tyre model (8 coefficients, B_f, C_f, D_f, E_f, B_r, C_r, D_r, E_r). Coefficients are seeded from the on-track sysid pipeline output (SIM_pacejka.txt).

Returns:: Complete parameter dictionary for the STP 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, n) where n is the model-specific row width; see gymkhana.envs.dynamic_models.DynamicModel.user_state_lens() for accepted widths and layouts. MB does not support full-state reset.
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).

disable_obs_min_max_recording(): Mute the close()-time print. Called by the SubprocVecEnv aggregator via env_method so the flag is set on the inner GKEnv, not the Monitor wrapper (which is what set_attr would target).

close(): Close the environment and release renderer resources.