:orphan:

:mod:`torchfilter.base._dynamics_model`
=======================================

.. py:module:: torchfilter.base._dynamics_model

.. autoapi-nested-parse::

   Private module; avoid importing from directly.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   torchfilter.base._dynamics_model.DynamicsModel



.. py:class:: DynamicsModel(*, state_dim: int)

   Bases: :class:`torch.nn.Module`, :class:`abc.ABC`

   .. autoapi-inheritance-diagram:: torchfilter.base._dynamics_model.DynamicsModel
      :parts: 1

   Base class for a generic differentiable dynamics model, with additive white
   Gaussian noise.

   Subclasses should override either ``forward`` or ``forward_loop`` for computing dynamics
   estimates.

   .. attribute:: state_dim
      

      Dimensionality of our state.

      :type: int


   .. method:: forward(self, *, initial_states: types.StatesTorch, controls: types.ControlsTorch) -> Tuple[types.StatesTorch, types.ScaleTrilTorch]

      Dynamics model forward pass, single timestep.

      Computes both predicted states and uncertainties. Note that uncertainties
      correspond to the (Cholesky decompositions of the) "Q" matrices in a standard
      linear dynamical system w/ additive white Gaussian noise. In other words, they
      should be lower triangular and not accumulate -- the uncertainty at at time ``t``
      should be computed as if the estimate at time ``t - 1`` is a ground-truth input.

      By default, this is implemented by bootstrapping the ``forward_loop()``
      method.

      :param initial_states: Initial states of our system. Shape should be
                             ``(N, state_dim)``.
      :type initial_states: torch.Tensor
      :param controls: Control inputs. Should be either a
                       dict of tensors or tensor of size ``(N, ...)``.
      :type controls: dict or torch.Tensor

      :returns: *Tuple[torch.Tensor, torch.Tensor]* -- Predicted states & uncertainties. States
                should have shape ``(N, state_dim)``\ , and uncertainties should be lower
                triangular with shape ``(N, state_dim, state_dim).``


   .. method:: forward_loop(self, *, initial_states: types.StatesTorch, controls: types.ControlsTorch) -> Tuple[types.StatesTorch, torch.Tensor]

      Dynamics model forward pass, over sequence length ``T`` and batch size
      ``N``.  By default, this is implemented by iteratively calling
      ``forward()``.

      Computes both predicted states and uncertainties. Note that uncertainties
      correspond to the (Cholesky decompositions of the) "Q" matrices in a standard
      linear dynamical system w/ additive white Gaussian noise. In other words, they
      should be lower triangular and not accumulate -- the uncertainty at at time ``t``
      should be computed as if the estimate at time ``t - 1`` is a ground-truth input.

      To inject code between timesteps (for example, to inspect hidden state),
      use ``register_forward_hook()``.

      :param initial_states: Initial states to pass to our
                             dynamics model. Shape should be ``(N, state_dim)``.
      :type initial_states: torch.Tensor
      :param controls: Control inputs. Should be either a
                       dict of tensors or tensor of size ``(T, N, ...)``.
      :type controls: dict or torch.Tensor

      :returns: *Tuple[torch.Tensor, torch.Tensor]* -- Predicted states & uncertainties. States
                should have shape ``(T, N, state_dim)``\ , and uncertainties should be lower
                triangular with shape ``(T, N, state_dim, state_dim).``


   .. method:: jacobian(self, initial_states: types.StatesTorch, controls: types.ControlsTorch) -> torch.Tensor

      Returns Jacobian of the dynamics model.

      :param states: Current state, size ``(N, state_dim)``.
      :type states: torch.Tensor
      :param controls: Control inputs. Should be either a
                       dict of tensors or tensor of size ``(N, ...)``.
      :type controls: dict or torch.Tensor

      :returns: *torch.Tensor* -- Jacobian, size ``(N, state_dim, state_dim)``