Base Classes

The base classes handle physical simulation and interaction between vehicles.

Source: gymkhana/envs/base_classes.py

RaceCar

Handles the simulation of a single vehicle’s dynamics model and laser scan generation.

Each RaceCar instance:

  • Maintains the vehicle’s state (position, velocity, orientation, etc.)

  • Steps the selected dynamics model forward in time

  • Generates simulated LiDAR scans via the laser model

Simulator

Orchestrates the multi-agent simulation, including:

  • Managing multiple RaceCar instances

  • Collision checking between agents and with track boundaries

  • Stepping all agents simultaneously for deterministic simulation

The step method (line 503) is the core simulation loop. All agents’ physics are stepped simultaneously, and all randomness is seeded for reproducibility. The explicit stepping enables faster-than-real-time execution.

API reference

Prototype of base classes Replacement of the old RaceCar, Simulator classes in C++ Author: Hongrui Zheng, Teodor Ilie

class gymkhana.envs.base_classes.RaceCar(params, seed, wall_deflection, action_type: CarAction, integrator=<gymkhana.envs.integrator.EulerIntegrator object>, model=DynamicModel.ST, is_ego=False, time_step=0.01, num_beams=1080, fov=4.7, prevent_instability=False, instability_bounds=None)

Single vehicle physics and laser scan simulation.

params

Vehicle parameters dictionary.

is_ego

Whether this is the ego vehicle.

time_step

Physics timestep in seconds.

num_beams

Number of beams in the laser scan.

fov

Field of view of the laser in radians.

state

State vector (size depends on model, e.g. 7 for ST).

accel

Current acceleration input.

steer_angle_vel

Current steering velocity input.

in_collision

Whether the vehicle is currently in collision.

scan_simulator = None
cosines = None
scan_angles = None
side_distances = None
update_params(params)

Update the physical parameters of the vehicle.

Parameters:

params – New vehicle parameters dictionary.

set_map(map: str | Track, map_scale: float = 1.0)

Set the map for the scan simulator.

Parameters:

  • map – Map name or a Track object.

  • map_scale – Scale factor for the map (default 1.0).

reset(pose, state=None)

Reset the vehicle to a pose or full state.

Parameters:

  • pose – Pose to reset to, shape (3,) as [x, y, yaw].

  • state – Optional model-specific user-facing state row; see gymkhana.envs.dynamic_models.DynamicModel.user_state_lens() for accepted widths and layouts. MB does not support full-state reset. If provided, pose is ignored.

ray_cast_agents(scan)

Ray cast onto other agents, returning a modified scan.

Parameters:

scan – Original scan range array, shape (n,).

Returns:

Modified scan with other agents occluding rays, shape (n,).

check_ttc(current_scan)

Check inverse Time-To-Collision (iTTC) against the environment.

Sets collision state if iTTC threshold is exceeded. Does not check collision with other agents (handled separately via GJK).

Parameters:

current_scan – Current laser scan array.

Returns:

True if a collision is detected, False otherwise.

update_pose(raw_steer, raw_throttle, skip_integration=False)

Step the vehicle’s physical simulation by one timestep.

Parameters:

  • raw_steer – Desired steering angle or velocity, depending on action type.

  • raw_throttle – Desired longitudinal velocity or acceleration, depending on action type.

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

Returns:

Current laser scan array after updating position.

update_opp_poses(opp_poses)

Update this vehicle’s information about other agents.

Parameters:

opp_poses – Poses of all other agents, shape (num_other_agents, 3).

update_scan(agent_scans, agent_index)

Update this vehicle’s laser scan based on current agent positions.

Separated from update_pose() because scans must be updated after all agents have moved to their new positions.

Parameters:

  • agent_scans – List of all agent scans, modified in-place.

  • agent_index – Index of this vehicle in the scans list.

property standard_state: dict

x, y, delta, v_x, v_y, yaw, yaw_rate, slip.

Type:

Standardized state dict with keys

class gymkhana.envs.base_classes.Simulator(params, num_agents, seed, num_beams, wall_deflection, action_type: CarAction, integrator=<class 'gymkhana.envs.integrator.Integrator'>, model=DynamicModel.ST, time_step=0.01, ego_idx=0, prevent_instability=False, instability_bounds=None)

Multi-agent simulation orchestrator.

Manages multiple RaceCar instances, steps their dynamics simultaneously, and checks collisions between agents and with track boundaries.

num_agents

Number of agents in the environment.

time_step

Physics time step in seconds.

agent_poses

All agent poses as array of shape (num_agents, 3).

agents

List of RaceCar instances.

collisions

Collision indicator per agent, shape (num_agents,).

collision_idx

Index of the agent each agent is colliding with, -1 if none.

agents: list[RaceCar]
set_map(map: str | Track, map_scale: float = 1.0)

Set the map for all agents’ scan simulators.

Parameters:

  • map – Map name or a Track object.

  • map_scale – Scale factor for the map (default 1.0).

update_params(params, agent_idx=-1)

Update vehicle parameters for one or all agents.

Parameters:

  • params – Vehicle parameters dictionary.

  • agent_idx – Index of the agent to update. If negative, updates all agents.

Raises:

IndexError – If agent_idx is out of range.

check_collision()

Check for collisions between agents using GJK and body vertices.

step(control_inputs, skip_integration=False)

Step the simulation by one timestep for all agents.

Parameters:

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

  • skip_integration – If True, skip dynamics integration (used during reset).

reset(poses, states=None)

Reset all agents to given poses or full states.

Parameters:

  • poses – Poses for all agents, shape (num_agents, 3).

  • states – Optional full states for all agents, 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. If provided, poses is ignored.

Raises:

ValueError – If the number of poses or states does not match num_agents.