torchdrivesim.kinematic ======================= .. py:module:: torchdrivesim.kinematic .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: torchdrivesim.kinematic.logger Classes ------- .. autoapisummary:: torchdrivesim.kinematic.KinematicModel torchdrivesim.kinematic.CompoundKinematicModel torchdrivesim.kinematic.TeleportingKinematicModel torchdrivesim.kinematic.SimpleKinematicModel torchdrivesim.kinematic.OrientedKinematicModel torchdrivesim.kinematic.KinematicBicycle torchdrivesim.kinematic.BicycleNoReversing torchdrivesim.kinematic.BicycleByDisplacement torchdrivesim.kinematic.BicycleByOrientedDisplacement Module Contents --------------- .. py:data:: logger :value: None .. py:class:: KinematicModel(dt: float = 0.1) Bases: :py:obj:`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. :param dt: Default time unit in seconds. .. py:attribute:: state_size :type: int :value: 4 .. py:attribute:: action_size :type: int :value: 4 .. py:attribute:: dt :value: 0.1 .. py:attribute:: state :value: None .. py:property:: batch_size :type: int .. py:method:: step(action: torch.Tensor, dt: Optional[float] = None) -> None :abstractmethod: Calculates and sets the next state given the current action. :param action: BxAc tensor :param dt: time delta, if not specified use object default .. py:method:: fit_action(future_state: torch.Tensor, current_state: Optional[torch.Tensor] = None, dt: Optional[float] = None) -> torch.Tensor :abstractmethod: Produces an action that applied to the current state would produce the given state, or some approximation thereof. :param future_state: BxSt tensor representing state to achieve :param current_state: BxSt tensor, if not specified use object's state :param dt: time step in seconds, if different from default :returns: BxAc action tensor .. py:method:: copy(other=None) Returns a shallow copy of the current object. Optionally takes a target which will be copied into. .. py:method:: to(device: torch.device) Moves all tensors to a given device in place. .. py:method:: set_state(state: torch.Tensor) -> None .. py:method:: get_state() -> torch.Tensor .. py:method:: get_params() -> Dict[str, torch.Tensor] Returns a dictionary of model parameters. .. py:method:: set_params(**kwargs) -> None Set custom parameters of the model, specified as tensors. .. py:method:: flattening(batch_shape) -> None Flattens batch dimensions for model parameters in place. .. py:method:: unflattening(batch_shape) -> None Reverse of `flattening`. .. py:method:: map_param(f) -> None Apply a function to all the parameters of the model. .. py:method:: normalize_action(action: torch.Tensor) -> torch.Tensor Normalizes the action to fit it in [-1,1] interval. Typically used to train neural policies. .. py:method:: denormalize_action(action: torch.Tensor) -> torch.Tensor Reverse of `normalize_action`. .. py:method:: pack_state(x: torch.Tensor, y: torch.Tensor, psi: torch.Tensor, speed: torch.Tensor) -> torch.Tensor :staticmethod: Packs the given state components as a BxSt tensor. Inputs should have shape (B,). .. py:method:: unpack_state(state: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor] :staticmethod: Reverse of `pack_state`. .. py:method:: extend(n: int) .. py:method:: select_batch_elements(idx) .. py:class:: CompoundKinematicModel(models: List[KinematicModel], model_assignments: torch.Tensor, dt: float = 0.1) Bases: :py:obj:`KinematicModel` A class that allows combining multiple kinematic models by splitting the batch, applying the models, then reassembling the tensor before returning. It does not allow duplicate parameter names across models. :param models: kinematic models to combine :param batch_assignments: tensor of integers assigning each element of the batch to a model in the list above .. py:attribute:: models .. py:attribute:: model_assignments .. py:attribute:: state_size .. py:attribute:: action_size .. py:property:: batch_assignments :type: torch.Tensor .. py:property:: batch_size :type: int .. py:property:: batch_shape :type: torch.Size .. py:method:: step(action: torch.Tensor, dt: Optional[float] = None) -> None Calculates and sets the next state given the current action. :param action: BxAc tensor :param dt: time delta, if not specified use object default .. py:method:: fit_action(future_state: torch.Tensor, current_state: Optional[torch.Tensor] = None, dt: Optional[float] = None) -> torch.Tensor Produces an action that applied to the current state would produce the given state, or some approximation thereof. :param future_state: BxSt tensor representing state to achieve :param current_state: BxSt tensor, if not specified use object's state :param dt: time step in seconds, if different from default :returns: BxAc action tensor .. py:method:: copy(other=None) Returns a shallow copy of the current object. Optionally takes a target which will be copied into. .. py:method:: to(device) Moves all tensors to a given device in place. .. py:method:: extend(n: int) .. py:method:: select_batch_elements(idx) .. py:method:: set_state(state: torch.Tensor) -> None .. py:method:: get_state() -> torch.Tensor .. py:method:: get_params() -> Dict[str, torch.Tensor] Returns a dictionary of model parameters. .. py:method:: set_params(**kwargs) -> None Set custom parameters of the model, specified as tensors. .. py:method:: flattening(batch_shape) -> None Flattens batch dimensions for model parameters in place. .. py:method:: unflattening(batch_shape) -> None Reverse of `flattening`. .. py:method:: map_param(f) -> None Apply a function to all the parameters of the model. .. py:method:: normalize_action(action: torch.Tensor) -> torch.Tensor Normalizes the action to fit it in [-1,1] interval. Typically used to train neural policies. .. py:method:: denormalize_action(action: torch.Tensor) -> torch.Tensor Reverse of `normalize_action`. .. py:class:: TeleportingKinematicModel(dt: float = 0.1) Bases: :py:obj:`KinematicModel` A trivial kinematic model where the action is the next state. .. py:method:: step(action, dt=None) Calculates and sets the next state given the current action. :param action: BxAc tensor :param dt: time delta, if not specified use object default .. py:method:: fit_action(future_state, current_state=None, dt=None) Produces an action that applied to the current state would produce the given state, or some approximation thereof. :param future_state: BxSt tensor representing state to achieve :param current_state: BxSt tensor, if not specified use object's state :param dt: time step in seconds, if different from default :returns: BxAc action tensor .. py:class:: SimpleKinematicModel(max_dx=20, max_dpsi=10 * np.pi, max_dv=5, dt=0.1) Bases: :py:obj:`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. :param max_dx: Normalization factor for action in x and y. :param max_dpsi: Normalization factor for action in orientation. :param max_dv: Normalization factor for action in speed. .. py:attribute:: max_dx :value: 20 .. py:attribute:: max_dpsi .. py:attribute:: max_dv :value: 5 .. py:attribute:: _normalization_factor .. py:method:: copy(other=None) Returns a shallow copy of the current object. Optionally takes a target which will be copied into. .. py:method:: to(device) Moves all tensors to a given device in place. .. py:method:: normalize_action(action) Normalizes the action to fit it in [-1,1] interval. Typically used to train neural policies. .. py:method:: denormalize_action(action) Reverse of `normalize_action`. .. py:method:: step(action, dt=None) Calculates and sets the next state given the current action. :param action: BxAc tensor :param dt: time delta, if not specified use object default .. py:method:: fit_action(future_state, current_state=None, dt=None) Produces an action that applied to the current state would produce the given state, or some approximation thereof. :param future_state: BxSt tensor representing state to achieve :param current_state: BxSt tensor, if not specified use object's state :param dt: time step in seconds, if different from default :returns: BxAc action tensor .. py:class:: OrientedKinematicModel(max_dx=20, max_dpsi=10 * np.pi, max_dv=5, dt=0.1) Bases: :py:obj:`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. .. py:method:: step(action, dt=None) Calculates and sets the next state given the current action. :param action: BxAc tensor :param dt: time delta, if not specified use object default .. py:method:: fit_action(future_state, current_state=None, dt=None) Produces an action that applied to the current state would produce the given state, or some approximation thereof. :param future_state: BxSt tensor representing state to achieve :param current_state: BxSt tensor, if not specified use object's state :param dt: time step in seconds, if different from default :returns: BxAc action tensor .. py:class:: KinematicBicycle(max_acceleration=5, max_steering=np.pi / 2, dt=0.1, left_handed=False) Bases: :py:obj:`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. :param max_acceleration: Normalization factor for acceleration. :param max_steering: Normalization factor for steering. :param dt: Default time step length. :param left_handed: Set if using a left-handed coordinate system for portability to right-handed coordinates. .. py:attribute:: action_size :type: int :value: 2 .. py:attribute:: max_acceleration :value: 5 .. py:attribute:: max_steering .. py:attribute:: left_handed :value: False .. py:attribute:: _normalization_factor .. py:attribute:: lr :value: None .. py:method:: copy(other=None) Returns a shallow copy of the current object. Optionally takes a target which will be copied into. .. py:method:: to(device) Moves all tensors to a given device in place. .. py:method:: get_params() Returns a dictionary of model parameters. .. py:method:: set_params(**kwargs) Set custom parameters of the model, specified as tensors. .. py:method:: flattening(batch_shape) Flattens batch dimensions for model parameters in place. .. py:method:: unflattening(batch_shape) Reverse of `flattening`. .. py:method:: map_param(f) Apply a function to all the parameters of the model. .. py:method:: normalize_action(action) Normalizes the action to fit it in [-1,1] interval. Typically used to train neural policies. .. py:method:: denormalize_action(action) Reverse of `normalize_action`. .. py:method:: step(action, dt=None) Calculates and sets the next state given the current action. :param action: BxAc tensor :param dt: time delta, if not specified use object default .. py:method:: fit_action(future_state, current_state=None, dt=None) Produces an action that applied to the current state would produce the given state, or some approximation thereof. :param future_state: BxSt tensor representing state to achieve :param current_state: BxSt tensor, if not specified use object's state :param dt: time step in seconds, if different from default :returns: BxAc action tensor .. py:class:: BicycleNoReversing(max_acceleration=5, max_steering=np.pi / 2, dt=0.1, left_handed=False) Bases: :py:obj:`KinematicBicycle` Modified bicycle model that brings a vehicle to full stop when it attempts to reverse. .. py:method:: step(action, dt=None) Calculates and sets the next state given the current action. :param action: BxAc tensor :param dt: time delta, if not specified use object default .. py:class:: BicycleByDisplacement(max_dx=20, dt=0.1) Bases: :py:obj:`KinematicBicycle` Similar to `SimpleKinematicModel`, but the action space is directed velocity. .. py:attribute:: max_dx :value: 20 .. py:attribute:: _xy_normalization_tensor .. py:method:: copy(other=None) Returns a shallow copy of the current object. Optionally takes a target which will be copied into. .. py:method:: to(device) Moves all tensors to a given device in place. .. py:method:: step(action, dt=None) Calculates and sets the next state given the current action. :param action: BxAc tensor :param dt: time delta, if not specified use object default .. py:method:: step_from_xy(xy, dt=None) .. py:method:: fit_action(future_state, current_state=None, dt=None) Produces an action that applied to the current state would produce the given state, or some approximation thereof. :param future_state: BxSt tensor representing state to achieve :param current_state: BxSt tensor, if not specified use object's state :param dt: time step in seconds, if different from default :returns: BxAc action tensor .. py:class:: BicycleByOrientedDisplacement(max_dx=20, dt=0.1) Bases: :py:obj:`BicycleByDisplacement` A combination of `BicycleByDisplacement` and `OrientedKinematicModel`. .. py:method:: step_from_xy(xy, dt=None) .. py:method:: fit_action(future_state, current_state=None, dt=None) Produces an action that applied to the current state would produce the given state, or some approximation thereof. :param future_state: BxSt tensor representing state to achieve :param current_state: BxSt tensor, if not specified use object's state :param dt: time step in seconds, if different from default :returns: BxAc action tensor