dair_pll.integrator

Classes for time integration on state spaces

This module implements an Integrator abstract type which is a convenience wrapper for various forms of integrating dynamics in time over a StateSpace. As state spaces are assumed to be the product space of a Lie group and its associated algebra (G x g), there are several options for which a “partial step” partial_step might be defined for mapping current states to next states:

  • x -> x’ in G x g (current state to next state)

  • x -> dx in g x R^n_v, and x’ = x * exp(dx) (current state to state delta)

  • x -> v’ in g, and q’ = q * exp(v’) (current state to next velocity)

  • x -> dv in R^n_v, v’ = v + dv (current state to velocity delta)

  • x -> q’ in G, and v’ = log(q’ * inv(q))/dt (current state to next configuration)

  • x -> dq in g, q’ = q * exp(dq), v’ = log(q’ * inv(q))/dt (current state to configuration delta).

Each option is implemented as a convenience class inheriting from Integrator.

In addition to this state mapping, the integrator allows for an additional hidden state denoted as carry to be propagated through .

Integrator objects have a simulation interface that requires an initial condition in the form of an initial state and carry.

class dair_pll.integrator.Integrator(space, partial_step_callback, dt)[source]

Bases: ABC, Module

Class that manages integration in time of given dynamics.

Takes in a partial_step callback object which defines the underlying dynamics abstractly. Inheriting classes makes this relationship concrete.

This class is primarily used for its simulate() method which integrates forward in time from a given initial condition.

Inits Integrator with specified dynamics.

Parameters:

  • space (StateSpace) – state space of system to be integrated.

  • partial_step_callback (Callable[[Tensor, Tensor], Tuple[Tensor, Tensor]]) – Dynamics defined as partial update from current state to next state. Exact usage is abstract.

  • dt (float) – time step.

partial_step_callback: typing.Optional[typing.Callable[[Tensor, Tensor], Tuple[Tensor, Tensor]]]
space: dair_pll.state_space.StateSpace
dt: float
out_size: int
partial_step(x, carry)[source]

Wrapper method for calling partial_step_callback

Return type:

Tuple[Tensor, Tensor]

simulate(x_0, carry_0, steps)[source]

Simulates forward in time from initial condition.

Parameters:

  • x_0 (Tensor) – (*, space.n_x) batch of initial condition states

  • carry_0 (Tensor) – (*, ?) batch of initial condition hidden states

  • steps (int) – number of steps to simulate forward in time (>= 0)

Return type:

Tuple[Tensor, Tensor]

Returns:

(*, space.n_x, steps + 1) simulated trajectory.

abstract step(x, carry)[source]

Takes single step in time.

Abstract wrapper which inheriting classes incorporate partial_step() into to complete a single time step.

Parameters:

  • x (Tensor) – (*, space.n_x) current state

  • carry (Tensor) – (*, ?) current hidden state

Return type:

Tuple[Tensor, Tensor]

Returns:

(*, space.n_x) next state (*, ?) next hidden state

static calc_out_size(space)[source]

Final dimension of output shape of partial_step()

Return type:

int

class dair_pll.integrator.StateIntegrator(space, partial_step_callback, dt)[source]

Bases: Integrator

Convenience class for Integrator where partial_step() maps current state directly to next state.

Inits Integrator with specified dynamics.

Parameters:

  • space (StateSpace) – state space of system to be integrated.

  • partial_step_callback (Callable[[Tensor, Tensor], Tuple[Tensor, Tensor]]) – Dynamics defined as partial update from current state to next state. Exact usage is abstract.

  • dt (float) – time step.

step(x, carry)[source]

Integrates by direct passthrough to partial_step()

Return type:

Tuple[Tensor, Tensor]

class dair_pll.integrator.DeltaStateIntegrator(space, partial_step_callback, dt)[source]

Bases: Integrator

Convenience class for Integrator where partial_step() maps current state to state delta.

Inits Integrator with specified dynamics.

Parameters:

  • space (StateSpace) – state space of system to be integrated.

  • partial_step_callback (Callable[[Tensor, Tensor], Tuple[Tensor, Tensor]]) – Dynamics defined as partial update from current state to next state. Exact usage is abstract.

  • dt (float) – time step.

step(x, carry)[source]

Integrates by perturbing current state by output of partial_step()

Return type:

Tuple[Tensor, Tensor]

static calc_out_size(space)[source]

Final dimension of output shape of partial_step()

Return type:

int

class dair_pll.integrator.VelocityIntegrator(space, partial_step_callback, dt)[source]

Bases: Integrator

Convenience class for Integrator where partial_step() maps current state to next velocity.

Inits Integrator with specified dynamics.

Parameters:

  • space (StateSpace) – state space of system to be integrated.

  • partial_step_callback (Callable[[Tensor, Tensor], Tuple[Tensor, Tensor]]) – Dynamics defined as partial update from current state to next state. Exact usage is abstract.

  • dt (float) – time step.

step(x, carry)[source]

Integrates by setting next velocity to output of partial_step() and implicit Euler integration of the configuration.

Return type:

Tuple[Tensor, Tensor]

static calc_out_size(space)[source]

Final dimension of output shape of partial_step()

Return type:

int

class dair_pll.integrator.DeltaVelocityIntegrator(space, partial_step_callback, dt)[source]

Bases: Integrator

Convenience class for Integrator where partial_step() maps current state to velocity delta.

Inits Integrator with specified dynamics.

Parameters:

  • space (StateSpace) – state space of system to be integrated.

  • partial_step_callback (Callable[[Tensor, Tensor], Tuple[Tensor, Tensor]]) – Dynamics defined as partial update from current state to next state. Exact usage is abstract.

  • dt (float) – time step.

step(x, carry)[source]

Integrates by perturbing current velocity by output of partial_step() and implicit Euler integration of the configuration.

Return type:

Tuple[Tensor, Tensor]

static calc_out_size(space)[source]

Final dimension of output shape of partial_step()

Return type:

int

class dair_pll.integrator.ConfigurationIntegrator(space, partial_step_callback, dt)[source]

Bases: Integrator

Convenience class for Integrator where partial_step() maps current state to next configuration.

Inits Integrator with specified dynamics.

Parameters:

  • space (StateSpace) – state space of system to be integrated.

  • partial_step_callback (Callable[[Tensor, Tensor], Tuple[Tensor, Tensor]]) – Dynamics defined as partial update from current state to next state. Exact usage is abstract.

  • dt (float) – time step.

step(x, carry)[source]

Integrates by setting next configuration to output of partial_step() and finite differencing for the next velocity.

Return type:

Tuple[Tensor, Tensor]

static calc_out_size(space)[source]

Final dimension of output shape of partial_step()

Return type:

int

class dair_pll.integrator.DeltaConfigurationIntegrator(space, partial_step_callback, dt)[source]

Bases: Integrator

Convenience class for Integrator where partial_step() maps current state to configuration delta.

Inits Integrator with specified dynamics.

Parameters:

  • space (StateSpace) – state space of system to be integrated.

  • partial_step_callback (Callable[[Tensor, Tensor], Tuple[Tensor, Tensor]]) – Dynamics defined as partial update from current state to next state. Exact usage is abstract.

  • dt (float) – time step.

step(x, carry)[source]

Integrates by perturbing current configuration by output of partial_step() and finite differencing for the next velocity.

Return type:

Tuple[Tensor, Tensor]

static calc_out_size(space)[source]

Final dimension of output shape of partial_step()

Return type:

int