Action System

The action system handles different control input types and optional normalization.

Source: gymkhana/envs/action.py

Action space

Actions are an ndarray of shape (num_agents, 2) where each row is [steering, longitudinal]:

action[0] — steering command (angle or velocity)
action[1] — longitudinal command (speed or acceleration)

Control input types

control_input is a list of two strings — one longitudinal type and one steering type, in any order:

Longitudinal:

"speed": Target velocity. Internally converted to acceleration via a P controller. Action space: [v_min, v_max].
"accl": Direct acceleration command. Action space: [-a_max, a_max]. Recommended for RL drift training for smooth control.

Steering:

"steering_angle": Target steering angle. Internally converted to steering velocity via a bang-bang controller. Action space: [s_min, s_max].
"steering_speed": Direct steering velocity command. Action space: [sv_min, sv_max].

Common combinations:

['speed', 'steering_angle'] — default, suitable for general use and classical controllers
['accl', 'steering_angle'] — recommended for RL tasks

Configuration

config = {
    'control_input': ['accl', 'steering_angle'],
    'normalize_act': True,   # Normalize action space to [-1, 1]
}

Normalization

When normalize_act is True, the action space is normalized to [-1, 1] for each dimension. The mapping depends on the action type:

accl: [-1, 1] maps to [-a_max, a_max]
speed: [-1, 1] maps to [v_min, v_max]
steering_angle: [-1, 1] maps to [s_min, s_max]
steering_speed: [-1, 1] maps to [sv_min, sv_max]

Normalization is supported for all action types and is generally recommended for RL training.

API reference

Action types and normalization for vehicle control inputs.

class gymkhana.envs.action.LongitudinalActionEnum(value)

Enum for longitudinal action types.

Members:: Accl: Direct acceleration control. Speed: Target speed control (converted to acceleration via P controller).

Accl = 1

Speed = 2

static from_string(action: str)

Return the action class for the given string identifier.

Parameters:: action – One of "accl" or "speed".
Returns:: The corresponding action class.
Raises:: ValueError – If the action string is not recognised.

static is_valid(action: str) → bool: Check whether a string is a valid longitudinal action type.

class gymkhana.envs.action.LongitudinalAction(normalize: bool)

Base class for longitudinal (speed/acceleration) actions.

Subclasses implement act() to convert a raw action value into an acceleration command suitable for the dynamics model. act() reads scaling factors live from params each call, so GKEnv.configure param updates take effect without rebuilding the action.

normalize: Whether actions are normalized to [-1, 1].

lower_limit: Lower bound of the action space.

upper_limit: Upper bound of the action space.

abstractmethod act(longitudinal_action: Any, **kwargs) → float

property type: str: String identifier for this action type (e.g. "accl", "speed").

property space: Space: Gymnasium Box space for this action dimension.

class gymkhana.envs.action.AcclAction(params: Dict, normalize: bool)

Direct acceleration control action.

When normalized, maps [-1, 1] to [-a_max, a_max].

act(action: float, state, params) → float

Return the acceleration command.

Parameters:

action – Normalized [-1, 1] or raw acceleration value.
state – Vehicle state vector (unused for direct acceleration).
params – Vehicle parameters dict.

Returns:

Acceleration in m/s^2.

class gymkhana.envs.action.SpeedAction(params: Dict, normalize: bool)

Target speed control action, converted to acceleration via a P controller.

When normalized, maps [-1, 1] to [v_min, v_max].

act(action: float, state: ndarray, params: Dict) → float

Return the acceleration command for a desired speed.

Parameters:

action – Normalized [-1, 1] or raw target speed value.
state – Vehicle state vector (index 3 is current velocity).
params – Vehicle parameters dict.

Returns:

Acceleration in m/s^2, computed by a proportional controller.

class gymkhana.envs.action.SteerAction(normalize: bool)

Base class for steering actions.

Subclasses implement act() to convert a raw action value into a steering velocity command suitable for the dynamics model. act() reads scaling factors live from params each call, so GKEnv.configure param updates take effect without rebuilding the action.

normalize: Whether actions are normalized to [-1, 1].

lower_limit: Lower bound of the action space.

upper_limit: Upper bound of the action space.

abstractmethod act(steer_action: Any, **kwargs) → float

property type: str: String identifier for this action type (e.g. "steering_angle").

property space: Space: Gymnasium Box space for this action dimension.

class gymkhana.envs.action.SteeringAngleAction(params: Dict, normalize: bool, timestep: float | None = None)

Target steering angle action.

With params["T_steer"] > 0 and a timestep, applies an exact ZOH first-order lag δ_dot = (δ_ref − δ)/T_steer; otherwise falls back to bang-bang. Normalized actions map [-1, 1] → [s_min, s_max].

act(action: float, state: ndarray, params: Dict) → float

Return steering velocity for a desired steering angle.

Parameters:

action – Normalized [-1, 1] or raw steering angle in radians.
state – Vehicle state vector (index 2 is current steering angle).
params – Vehicle parameters dict.

Returns:

Steering velocity in rad/s.

class gymkhana.envs.action.SteeringSpeedAction(params: Dict, normalize: bool)

Direct steering velocity action.

When normalized, maps [-1, 1] to [sv_min, sv_max] (guaranteed symmetric).

act(action: float, state: ndarray, params: Dict) → float

Return the steering velocity command.

Parameters:

action – Normalized [-1, 1] or raw steering velocity in rad/s.
state – Vehicle state vector (unused for direct steering velocity).
params – Vehicle parameters dict.

Returns:

Steering velocity in rad/s.

class gymkhana.envs.action.SteerActionEnum(value)

Enum for steering action types.

Members:: Steering_Angle: Target angle control (uses bang-bang controller). Steering_Speed: Direct steering velocity control.

Steering_Angle = 1

Steering_Speed = 2

static from_string(action: str)

Return the action class for the given string identifier.

Parameters:: action – One of "steering_angle" or "steering_speed".
Returns:: The corresponding action class.
Raises:: ValueError – If the action string is not recognised.

static is_valid(action: str) → bool: Check whether a string is a valid steering action type.

class gymkhana.envs.action.CarAction(control_mode: str | list[str], params: Dict, normalize: bool, timestep: float | None = None)

Combined steering and longitudinal action for a single vehicle.

Parses control_mode to select one steering action and one longitudinal action, then delegates to them in act().

normalize: Whether actions are normalized to [-1, 1].

act(action: Any, **kwargs) → Tuple[float, float]

Convert a [steer, longitudinal] action pair into control commands.

Parameters:

action – Two-element array [steer_action, longitudinal_action].
**kwargs – Forwarded to the underlying action handlers (state, params).

Returns:

Tuple of (acceleration, steering_velocity).

property type: Tuple[str, str]: Tuple of (steering_type, longitudinal_type) string identifiers.

property steer_bounds: Tuple[float, float]: (lower, upper) bounds for the steering action dimension.

property throttle_bounds: Tuple[float, float]: (lower, upper) bounds for the longitudinal action dimension.

property space: Space: Combined 2-D Gymnasium Box space [steer, longitudinal].

gymkhana.envs.action.from_single_to_multi_action_space(single_agent_action_space: Box, num_agents: int) → Box

Tile a single-agent action space into a multi-agent action space.

Parameters:

single_agent_action_space – A 1-D Box space for one agent.
num_agents – Number of agents.

Returns:

A Box space of shape (num_agents, action_dim).