`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.

Module Contents#

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.

Attributes#

logger

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

torchdrivesim.kinematic#

Module Contents#

Classes#

Attributes#

`torchdrivesim.kinematic`#