Module¶

Optimal control layers¶

Optimal control problem formulation layers.

class qpmpc_layers.optimal_control.Start(state_dim, dtype=None)¶

First layer of an optimal control problem (OCP) graph.

dtype¶: Desired data type of intermediate tensors.

state_dim¶: Dimension of the state space.

forward()¶

Get a blank OCP quadratic program.

Return type:: QP
Returns:: Quadratic program for a new OCP.

class qpmpc_layers.optimal_control.Step(cost, dynamics, constraint=None)¶

Transition of the optimal control problem.

An action step from step \(k\) extends the episode vector \(\tau_k = (x_0, u_0, \ldots, x_{k-1}, u_{k-1}, x_k)\) with the pair \((u_k, x_{k+1})\), where \(u_k\) is the action taken at step \(k\) and \(x_{k+1}\) is the next state after applying transition Dynamics:

\[x_{k+1} = A x_k + B u_k\]

The action step contributes a qpmpc_layers.types.StageCost \(\ell(x_k, u_k)\) of the action step to the total cost:

\[\ell(x_k, u_k) = \frac{1}{2} x_k^T Q x_k + q^T x_k + \frac{1}{2} u_k^T R u_k + r^T u_k\]

We can also apply a state-action inequality Constraint to the step:

\[e \leq C x_k + D u_k \leq f\]

cost¶: Contribution of the action step to the overall optimization cost.

dynamics¶: Linear dynamics of the action step.

constraint¶: Optional inequality constraints on the state and action of the step.

forward(prev)¶

Forward calculation of the action step.

Parameters:: prev (QP) – Quadratic program of the optimal control problem so far.
Return type:: QP
Returns:: Quadratic program of the optimal control problem with the added action step.

class qpmpc_layers.optimal_control.Terminate(cost)¶

Set terminal cost of an optimal control problem (OCP) graph.

The terminal step adds a qpmpc_layers.types.TerminalCost \(\ell(x_N)\) based on the terminal state \(x_N\):

\[\ell(x_N) = \frac{1}{2} x_N^T Q x_N + q^T x_N\]

Note

Don’t append Step layers after this one.

cost¶: Cost on the terminal state.

forward(prev)¶

Forward calculation of the terminal step.

Parameters:: prev (QP) – Quadratic program of the optimal control problem so far.
Return type:: QP
Returns:: Quadratic program of the terminated optimal control problem.

class qpmpc_layers.optimal_control.Wrap(state_dim)¶

Set the initial state constraint to complete an OCP.

forward(prev, x_init)¶

Forward calculation of the wrapping step.

Parameters:

prev (QP) – Quadratic program of the optimal control problem so far.
x_init (Tensor) – Initial state of the problem.

Return type:

QP

Returns:

Quadratic program of the completed optimal control problem.

Linear time-invariant systems¶

Submodule for linear time-invariant systems.

class qpmpc_layers.lti.Integrator(nb_steps, dynamics)¶

Integrator for a linear time-invariant system.

An integrator applies an integration scheme to system dynamics. In this instance: explicit Euler to linear time-invariant dynamics.

dynamics¶: Dynamics of the system.

forward(U, x_init)¶

Forward computation performed by the module.

Parameters:

U (Tensor) – Input trajectory \(U_N = (u_0, \ldots, u_{N-1})\).
x_init (Tensor) – Initial state \(x_\mathit{init}\).

Return type:

Tensor

Returns:

Flat state trajectory vector \(X_N = [x_0 \ldots x_N]\) resulting from integrating the input trajectory from the initial state.

class qpmpc_layers.lti.OptimalControlProblem(nb_steps, stage_cost, dynamics, terminal_cost=None, constraint=None)¶

Optimal control problem for a linear time-invariant system.

The cost function of our problem is the sum of qpmpc_layers.types.StageCost’s and a qpmpc_layers.types.TerminalCost:

\[J(X_N, U_N) = \sum_{k=0}^{N-1} \ell(x_k, u_k) + \ell(x_N)\]

where \(X_N = (x_0, \ldots, x_N)\) is the state trajectory vector and \(U_N = (u_0, \ldots, u_{N-1})\) is the input trajectory vector. Our overall cost is quadratic, so that the optimal control problem can be cast as a qpmpc_layers.types.QP.

constraint¶: Optional inequality constraints on the state and action of a step.

dynamics¶: Dynamics of the system.

stage_cost¶: Contribution of an action step to the overall optimization cost.

terminal_cost¶: Terminal-state cost.

forward(x_init)¶

Forward computation performed by the module.

Parameters:: x_init (Tensor) – Initial state of the problem.
Return type:: QP
Returns:: QP for the OCP starting from the prescribed initial state.

Types¶

Types defined by the library.

class qpmpc_layers.types.Constraint(C=None, D=None, e=None, f=None)¶

Inequality constraint along the optimal control problem.

Inequalities are expressed as:

\[e \leq C x_k + D u_k \leq f\]

C¶: State constraint matrix in \(C x_k\).

D¶: Input constraint matrix in \(D u_k\).

e¶: Optional constraint lower bound \(e\) (default: no lower bound).

f¶: Optional constraint upper bound \(f\) (default: no upper bound).

property dtype: dtype¶: Get the PyTorch datatype of the constraint tensors.

property size: int¶: Number of inequality constraints.

class qpmpc_layers.types.Dynamics(A, B)¶

Dynamics of an optimal control problem step.

The dynamics of step \(k\) are given by:

\[x_{k+1} = A x_k + B u_k\]

A¶: State transition matrix in \(A x_k\).

B¶: Action transition matrix in \(B u_k\).

property dtype: dtype¶: Get the PyTorch datatype of the dynamics step tensors.

class qpmpc_layers.types.IntegrationMap(Phi, Psi, phi, psi)¶

Linear map from (initial state, inputs) to future state trajectory.

Given the initial state \(x_0\) and the stacked vector of control inputs \(U_k = (u_0, u_1, \ldots, u_{k-1})\), the state map provides the stacked vector \(X_k = (x_0, \ldots, x_k)\) of future states as:

\[X_k = \Psi U_k + \Phi x_0\]

This datastructure also maintains \(\psi\) and \(\phi\) mapping to the last state in the trajectory:

\[x_k = \psi U_k + \phi x_0\]

Phi¶: Linear map from initial state to future states.

Psi¶: Linear map from stacked inputs to future states.

phi¶: Linear map from initial state to last state.

psi¶: Linear map from stacked inputs to last state.

class qpmpc_layers.types.QP(H, g, A, b, C, l, u)¶

Quadratic program in ProxQP format.

\[\begin{split}\begin{split}\begin{array}{ll} \underset{x}{\mbox{minimize}} & \frac{1}{2} x^T H x + g^T x \\ \mbox{subject to} & A x = b \\ & l \leq C x \leq u \end{array}\end{split}\end{split}\]

H¶: Cost matrix.

g¶: Cost vector.

A¶: Equality-constraint matrix.

b¶: Equality-constraint vector.

C¶: Inequality-constraint matrix.

l¶: Inequality-constraint lower bound.

u¶: Inequality-constraint upper bound..

unpack()¶

Unpack dataclass as a tuple.

Return type:: Tuple[Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor]
Returns:: Tuple \((H, g, A, b, C, l, u)\) of the quadratic program.

class qpmpc_layers.types.StageCost(Q, R, q=None, r=None)¶

Cost of a transition in the optimal control problem.

The quadratic cost expression is defined by matrices \((Q, R)\) and vectors \((q, r)\) so that the contribution \(\ell(x_k, u_k)\) to the total cost is:

\[\ell(x_k, u_k) = \frac{1}{2} x_k^T Q x_k + q^T x_k + \frac{1}{2} u_k^T R u_k + r^T u_k\]

Q¶: State cost matrix in \(x_k^T Q x_k\).

R¶: Action cost matrix in \(u_k^T R u_k\).

q¶: Optional state cost vector in \(q^T x_k\) (default: zero).

r¶: Optional action cost vector in \(r^T u_k\) (default: zero).

property dtype: dtype¶: Get the PyTorch datatype of the stage cost tensors.

class qpmpc_layers.types.TerminalCost(Q, q=None)¶

Cost on the last state of the optimal control problem.

The quadratic cost expression is defined by matrix \(Q\) and vector \(q\) so that the cost \(\ell(x_k)\) is:

\[\ell(x_k) = \frac{1}{2} x_k^T Q x_k + q^T x_k\]

where \(k\) is the index of the last step in the optimal control problem.

Q¶: State cost matrix in \(x_k^T Q x_k\).

q¶: Optional state cost vector in \(q^T x_k\) (default: zero).

property dtype: dtype¶: Get the PyTorch datatype of the terminal cost tensors.