torchdrivesim.kinematic

Kinematic models define action spaces for agents and optionally constrain their motion. The constraints from kinematic models are computed independently for different agents. We currently provide the kinematic bicycle model and an unconstrained kinematic model, both with various parameterizations of the action space.

Attributes

Classes

KinematicModel

A generic kinematic base class. Minimum subclass needs to define action_size, step and fit_action.

TeleportingKinematicModel

A trivial kinematic model where the action is the next state.

SimpleKinematicModel

A simple kinematic model where the action is the gradient of the state vector with respect to time.

OrientedKinematicModel

Just like SimpleKinematicModel, but the action coordinate frame rotates with the agent,

KinematicBicycle

A kinematic bicycle model where steering is applied to the geometric center directly as beta.

BicycleNoReversing

Modified bicycle model that brings a vehicle to full stop when it attempts to reverse.

BicycleByDisplacement

Similar to SimpleKinematicModel, but the action space is directed velocity.

BicycleByOrientedDisplacement

A combination of BicycleByDisplacement and OrientedKinematicModel.

Functions

rotate(→ torch.Tensor)

Rotate the vector counterclockwise (from x towards y).

Module Contents

torchdrivesim.kinematic.rotate(v: torch.Tensor, angle: torch.Tensor) torch.Tensor[source]

Rotate the vector counterclockwise (from x towards y). Works correctly in batch mode.

Parameters:
  • v – tensor of shape Sx2 representing points

  • angle – tensor of shape Sx1 representing rotation angle

Returns:

Sx2 tensor of rotated points

torchdrivesim.kinematic.logger[source]
class torchdrivesim.kinematic.KinematicModel(dt: float = 0.1)[source]

Bases: abc.ABC

A generic kinematic base class. Minimum subclass needs to define action_size, step and fit_action. Designed to be used in batch mode. Subclasses may include additional model parameters with arbitrary names.

Parameters:

dt – Default time unit in seconds.

state_size: int = 4[source]
action_size: int = 4[source]
abstract step(action: torch.Tensor, dt: float | None = None) None[source]

Calculates and sets the next state given the current action.

Parameters:
  • action – BxAc tensor

  • dt – time delta, if not specified use object default

Returns:

BxSt tensor representing the new state at time t+dt

abstract fit_action(future_state: torch.Tensor, current_state: torch.Tensor | None = None, dt: float | None = None) torch.Tensor[source]

Produces an action that applied to the current state would produce the given state, or some approximation thereof.

Parameters:
  • future_state – BxSt tensor representing state to achieve

  • current_state – BxSt tensor, if not specified use object’s state

  • dt – time step in seconds, if different from default

Returns:

BxAc action tensor

copy(other=None)[source]

Returns a shallow copy of the current object. Optionally takes a target which will be copied into.

to(device: torch.device)[source]

Moves all tensors to a given device in place.

set_state(state: torch.Tensor) None[source]
get_state() torch.Tensor[source]
get_params() Dict[str, torch.Tensor][source]

Returns a dictionary of model parameters.

set_params(**kwargs) None[source]

Set custom parameters of the model, specified as tensors.

flattening(batch_shape) None[source]

Flattens batch dimensions for model parameters in place.

unflattening(batch_shape) None[source]

Reverse of flattening.

map_param(f) None[source]

Apply a function to all the parameters of the model.

normalize_action(action: torch.Tensor) torch.Tensor[source]

Normalizes the action to fit it in [-1,1] interval. Typically used to train neural policies.

denormalize_action(action: torch.Tensor) torch.Tensor[source]

Reverse of normalize_action.

static pack_state(x: torch.Tensor, y: torch.Tensor, psi: torch.Tensor, speed: torch.Tensor) torch.Tensor[source]

Packs the given state components as a BxSt tensor. Inputs should have shape (B,).

static unpack_state(state: torch.Tensor) Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor][source]

Reverse of pack_state.

class torchdrivesim.kinematic.TeleportingKinematicModel(dt: float = 0.1)[source]

Bases: KinematicModel

A trivial kinematic model where the action is the next state.

step(action, dt=None)[source]

Calculates and sets the next state given the current action.

Parameters:
  • action – BxAc tensor

  • dt – time delta, if not specified use object default

Returns:

BxSt tensor representing the new state at time t+dt

fit_action(future_state, current_state=None, dt=None)[source]

Produces an action that applied to the current state would produce the given state, or some approximation thereof.

Parameters:
  • future_state – BxSt tensor representing state to achieve

  • current_state – BxSt tensor, if not specified use object’s state

  • dt – time step in seconds, if different from default

Returns:

BxAc action tensor

class torchdrivesim.kinematic.SimpleKinematicModel(max_dx=20, max_dpsi=10 * np.pi, max_dv=5, dt=0.1)[source]

Bases: KinematicModel

A simple kinematic model where the action is the gradient of the state vector with respect to time. The action is specified in units of constructor arguments.

Parameters:
  • max_dx – Normalization factor for action in x and y.

  • max_dpsi – Normalization factor for action in orientation.

  • max_dv – Normalization factor for action in speed.

copy(other=None)[source]

Returns a shallow copy of the current object. Optionally takes a target which will be copied into.

normalize_action(action)[source]

Normalizes the action to fit it in [-1,1] interval. Typically used to train neural policies.

denormalize_action(action)[source]

Reverse of normalize_action.

step(action, dt=None)[source]

Calculates and sets the next state given the current action.

Parameters:
  • action – BxAc tensor

  • dt – time delta, if not specified use object default

Returns:

BxSt tensor representing the new state at time t+dt

fit_action(future_state, current_state=None, dt=None)[source]

Produces an action that applied to the current state would produce the given state, or some approximation thereof.

Parameters:
  • future_state – BxSt tensor representing state to achieve

  • current_state – BxSt tensor, if not specified use object’s state

  • dt – time step in seconds, if different from default

Returns:

BxAc action tensor

class torchdrivesim.kinematic.OrientedKinematicModel(max_dx=20, max_dpsi=10 * np.pi, max_dv=5, dt=0.1)[source]

Bases: SimpleKinematicModel

Just like SimpleKinematicModel, but the action coordinate frame rotates with the agent, so that the x-axis of the action space always points forward.

step(action, dt=None)[source]

Calculates and sets the next state given the current action.

Parameters:
  • action – BxAc tensor

  • dt – time delta, if not specified use object default

Returns:

BxSt tensor representing the new state at time t+dt

fit_action(future_state, current_state=None, dt=None)[source]

Produces an action that applied to the current state would produce the given state, or some approximation thereof.

Parameters:
  • future_state – BxSt tensor representing state to achieve

  • current_state – BxSt tensor, if not specified use object’s state

  • dt – time step in seconds, if different from default

Returns:

BxAc action tensor

class torchdrivesim.kinematic.KinematicBicycle(max_acceleration=5, max_steering=np.pi / 2, dt=0.1, left_handed=False)[source]

Bases: KinematicModel

A kinematic bicycle model where steering is applied to the geometric center directly as beta. The only parameter is the distance between the center and the rear axis, called ‘lr’. The action space is (acceleration, steering), in the units specified by constructor arguments. By default, steering is constrained to a right angle, so negative speed is needed to reverse.

Parameters:
  • max_acceleration – Normalization factor for acceleration.

  • max_steering – Normalization factor for steering.

  • dt – Default time step length.

  • left_handed – Set if using a left-handed coordinate system for portability to right-handed coordinates.

action_size: int = 2[source]
copy(other=None)[source]

Returns a shallow copy of the current object. Optionally takes a target which will be copied into.

get_params()[source]

Returns a dictionary of model parameters.

set_params(**kwargs)[source]

Set custom parameters of the model, specified as tensors.

flattening(batch_shape)[source]

Flattens batch dimensions for model parameters in place.

unflattening(batch_shape)[source]

Reverse of flattening.

map_param(f)[source]

Apply a function to all the parameters of the model.

normalize_action(action)[source]

Normalizes the action to fit it in [-1,1] interval. Typically used to train neural policies.

denormalize_action(action)[source]

Reverse of normalize_action.

step(action, dt=None)[source]

Calculates and sets the next state given the current action.

Parameters:
  • action – BxAc tensor

  • dt – time delta, if not specified use object default

Returns:

BxSt tensor representing the new state at time t+dt

fit_action(future_state, current_state=None, dt=None)[source]

Produces an action that applied to the current state would produce the given state, or some approximation thereof.

Parameters:
  • future_state – BxSt tensor representing state to achieve

  • current_state – BxSt tensor, if not specified use object’s state

  • dt – time step in seconds, if different from default

Returns:

BxAc action tensor

class torchdrivesim.kinematic.BicycleNoReversing(max_acceleration=5, max_steering=np.pi / 2, dt=0.1, left_handed=False)[source]

Bases: KinematicBicycle

Modified bicycle model that brings a vehicle to full stop when it attempts to reverse.

step(action, dt=None)[source]

Calculates and sets the next state given the current action.

Parameters:
  • action – BxAc tensor

  • dt – time delta, if not specified use object default

Returns:

BxSt tensor representing the new state at time t+dt

class torchdrivesim.kinematic.BicycleByDisplacement(max_dx=20, dt=0.1)[source]

Bases: KinematicBicycle

Similar to SimpleKinematicModel, but the action space is directed velocity.

copy(other=None)[source]

Returns a shallow copy of the current object. Optionally takes a target which will be copied into.

step(action, dt=None)[source]

Calculates and sets the next state given the current action.

Parameters:
  • action – BxAc tensor

  • dt – time delta, if not specified use object default

Returns:

BxSt tensor representing the new state at time t+dt

step_from_xy(xy, dt=None)[source]
fit_action(future_state, current_state=None, dt=None)[source]

Produces an action that applied to the current state would produce the given state, or some approximation thereof.

Parameters:
  • future_state – BxSt tensor representing state to achieve

  • current_state – BxSt tensor, if not specified use object’s state

  • dt – time step in seconds, if different from default

Returns:

BxAc action tensor

class torchdrivesim.kinematic.BicycleByOrientedDisplacement(max_dx=20, dt=0.1)[source]

Bases: BicycleByDisplacement

A combination of BicycleByDisplacement and OrientedKinematicModel.

step_from_xy(xy, dt=None)[source]
fit_action(future_state, current_state=None, dt=None)[source]

Produces an action that applied to the current state would produce the given state, or some approximation thereof.

Parameters:
  • future_state – BxSt tensor representing state to achieve

  • current_state – BxSt tensor, if not specified use object’s state

  • dt – time step in seconds, if different from default

Returns:

BxAc action tensor