MPC

MPC#

class do_dpc.dpc.mpc.MPC(dpc_params, training_data, n_state, **Kwargs)[source]#

Bases: DPC, ABC

Abstract class for implementing MPC based on DPC. The matrices A, B, C, D and the Kalman filter gain K can be calculated differently for different methods.

Parameters:

  • n_state (int) – Number of states in the system. Must be greater than or equal to 1.

  • **Kwargs – Additional keyword arguments.

Raises:

ValueError – If n_state is less than 1.

n_state#

Number of states in the system.

Type:

int

x_cp#

Control parameter representing the state vector.

Type:

cp.Parameter

mpc_cf_gains#

Calculated closed-form gains for the MPC controller.

Type:

MPCClosedFormSolutionMatrices

Methods#

add_custom_constraints#

do_dpc.dpc.mpc.MPC.add_custom_constraints(self, constraints)#

Adds custom constraints to the optimization problem.

Note

  • Users should access cvxpy parameters and decision variables directly from the DPC class.

  • All such attributes are denoted by the _cp suffix.

  • Ensure that added constraints do not conflict with existing ones.

  • For simple linear inequality constraints, prefer using set_input_constraint or set_output_constraint.

Parameters:

constraints (list[Constraint]) – A list of cvxpy constraints.

add_input_constraints#

do_dpc.dpc.mpc.MPC.add_input_constraints(self, u_bounds)#

Sets input constraints based on provided bounds.

Parameters:

u_bounds (Bounds) – An instance of Bounds containing upper (max_values) and lower (min_values) constraints for the control inputs.

Raises:

  • ValueError – If u_bounds.max_values and u_bounds.min_values have incorrect shapes.

  • ValueError – If u_bounds.max_values is smaller than u_bounds.min_values.

Special Cases:

  • To impose no bounds on specific inputs, set np.inf as the upper bound and -np.inf as the lower bound.

add_linear_constraints#

do_dpc.dpc.mpc.MPC.add_linear_constraints(self, A, b)#

Adds linear inequality constraints to the optimization problem.

The constraints are applied in the form:

A @ [ y_f u_f ]^T <= b

where:

  • A is a matrix of shape (n_constraints, n_y_f + n_u_f)

  • y_f (future outputs) is of shape (n_y_f, )

  • u_f (future inputs) is of shape (n_u_f, )

  • b is a vector of shape (n_constraints, )

Parameters:

  • A (np.ndarray) – Constraint matrix of shape (n_constraints, n_y_f + n_u_f).

  • b (np.ndarray) – Constraint vector of shape (n_constraints, ).

Raises:

  • ValueError – If A and b have incompatible shapes.

  • TypeError – If A or b are not numpy arrays.

  • Warning – If the first p columns of A are nonzero, indicating constraints on the first outputs.

add_terminal_output_constraints#

do_dpc.dpc.mpc.MPC.add_terminal_output_constraints(self, y_bounds)#

Adds terminal output constraints for the final step of the prediction horizon.

Notes

  • Only the final predicted output in the finite future horizon is constrained.

  • Due to system lag, immediate output constraints may not always be enforceable.

  • This design choice enhances solver feasibility for a wide range of systems.

  • If stricter constraints are needed, use add_custom_constraints.

Parameters:

y_bounds (Bounds) – A Bounds instance defining upper (max_values) and lower (min_values) constraints for system outputs.

Raises:

  • ValueError – If y_bounds.max_values and y_bounds.min_values have incorrect shapes.

  • ValueError – If any element in y_bounds.max_values is smaller than its corresponding y_bounds.min_values.

Special Cases:

  • To impose no bounds on specific outputs, set np.inf as the upper bound and -np.inf as the lower bound.

build_optimization_problem#

do_dpc.dpc.mpc.MPC.build_optimization_problem(self)#

Constructs the DPC optimization problem.

\[\begin{split}\min_{u_f, \cdot} &\quad \|y_f - y_r\|_Q^2 + \|u_f - u_r\|_R^2 + r(\cdot) \\ \text{s.t.} &\quad y_f = f(\cdot) \\ &\quad u_f \in \mathcal{U}, \quad y_f \in \mathcal{Y}\end{split}\]

where \(r(\cdot)\), \(f(\cdot)\) are linear functions which utilize matrices calculated in the Offline Calculations. Additional slack decision variables can be introduced. \(r(\cdot)\), \(f(\cdot)\) differ between different DPC algorithm.

The constraints for \(u_f\), \(y_f\) are handled by other methods.

calculate_closed_form_solution_matrices#

do_dpc.dpc.mpc.MPC.calculate_closed_form_solution_matrices(self)#

Cannot be implemented as the closed form is not calculated as: u_f^star = K_z_p z_p + …

Return type:

Optional[DPCClosedFormSolutionMatrices]

calculate_predictor_matrices#

do_dpc.dpc.mpc.MPC.calculate_predictor_matrices(self)#

Calculates the offline data required for the MPC controller.

This method computes the extended observability matrix (Gamma) and the matrix mapping future inputs to future outputs (H_u) based on the system’s state-space representation matrices (A, B, C, D) and control parameters (tau_f, p, m).

Returns:

An instance containing the computed Gamma, H_u, system data (sys),

and the infinite horizon Kalman gain (K).

Return type:

MPCPredictorMatrices

calculate_regularization_matrices#

do_dpc.dpc.mpc.MPC.calculate_regularization_matrices(self)#

Currently there is no regularization cost for the MPC algorithm.

Return type:

MPCRegularizationMatrices

calculate_system_data#

do_dpc.dpc.mpc.MPC.calculate_system_data(self)#

Abstract method to calculate the system data, including the state-space matrices and Kalman filter gain.

Returns:

An instance containing the system matrices and Kalman filter gain.

Return type:

MPCSystemMatrices

get_next_control_action#

do_dpc.dpc.mpc.MPC.get_next_control_action(self)#

Retrieves the next computed control input.

Returns:

The next control input of shape (m,).

Return type:

np.ndarray

Raises:

  • IndexError – If the control horizon is exceeded.

  • RuntimeError – If the optimization problem has not been solved or the solution is invalid.

get_predictor_constraint_expression#

do_dpc.dpc.mpc.MPC.get_predictor_constraint_expression(self)#

Calculates and returns the CVXPY constraint for the predictor constraint.

The predictor constraint is calculated as follows:

\[y_f = \Gamma x + H_u u_f\]
Returns:

The CVXPY constraint for the predictor constraint.

Return type:

cp.Constraint

get_regularization_cost_expression#

do_dpc.dpc.mpc.MPC.get_regularization_cost_expression(self)#

Currently there is no regularization cost implemented for the MPC algorithm.

Return type:

Expression

instantiate#

do_dpc.dpc.mpc.MPC.instantiate(dpc_type, *args, **kwargs)#

Factory method to create an instance of a registered DPC subclass.

Parameters:

  • dpc_type (str) – The type of DPC controller to instantiate.

  • *args – Positional arguments for the subclass constructor.

  • **kwargs – Keyword arguments for the subclass constructor.

Returns:

An instance of the corresponding DPC subclass.

Return type:

DPC

Raises:

ValueError – If the specified dpc_type is not registered.

register#

do_dpc.dpc.mpc.MPC.register(dpc_type)#

Decorator to register subclasses for dynamic instantiation.

Usage:

@DPC.register(“my_dpc”) class MyDPC(DPC):

…

Parameters:

dpc_type (str) – Name of the DPC subclass type.

Returns:

The decorator function.

Return type:

Callable[[Type[“DPC”]], Type[“DPC”]]

reset_constraints#

do_dpc.dpc.mpc.MPC.reset_constraints(self)#

Removes all existing constraints from the optimization problem.

Return type:

None

set_state_x#

do_dpc.dpc.mpc.MPC.set_state_x(self, x_new)#

Sets the state for the MPC controller.

Parameters:

x_new (np.ndarray) – New state vector. Must be of shape (self.n_state,).

Raises:

ValueError – If x_new does not match the required shape.

solve#

do_dpc.dpc.mpc.MPC.solve(self, verbose=False, solver='SCS', **kwargs)#

Solves the optimization problem for the MPC controller.

This method performs the following steps:

  1. Updates the state using the Kalman Filter.

  2. If the problem is unconstrained, it uses the MPC closed-form gains. Otherwise, it solves the optimization problem as implemented in the DPC class.

update_past_measurements#

do_dpc.dpc.mpc.MPC.update_past_measurements(self, z_p_new)#

Updates the stored past measurements with new incoming data.

Parameters:

z_p_new (np.ndarray) – New past measurement data (shape (mp,)).

Raises:

ValueError – If z_p_new does not match the expected shape.

update_tracking_reference#

do_dpc.dpc.mpc.MPC.update_tracking_reference(self, y_r_new, u_r_new)#

Updates the tracking reference trajectory.

Parameters:

  • y_r_new (np.ndarray) – New reference trajectory for outputs (shape (p,)).

  • u_r_new (np.ndarray) – New reference trajectory for inputs (shape (m,)).

Raises:

  • ValueError – If y_r_new does not match expected dimensions (p,).

  • ValueError – If u_r_new does not match expected dimensions (m,).

Contents