TPC

TPC#

class do_dpc.dpc.tpc.TPC(dpc_params, training_data)[source]#

Bases: DPC

Implements Transient Predictive Control based on DPC.

tpc_helper_matrices#

Holds helper matrices.

Type:

TPCHelperMatrices

Methods#

add_custom_constraints#

do_dpc.dpc.tpc.TPC.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.tpc.TPC.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.tpc.TPC.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.tpc.TPC.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.tpc.TPC.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.tpc.TPC.calculate_closed_form_solution_matrices(self)#

Calculates and returns the closed-form gains for the DPC controller.

The gains are calculated using the pseudo-inverse of the transformed matrices.

Returns:

The closed-form gains for the DPC controller,

Return type:

Optional[DPCClosedFormSolutionMatrices]

calculate_predictor_matrices#

do_dpc.dpc.tpc.TPC.calculate_predictor_matrices(self)#

Calculates and returns the predictor matrices for future control inputs and past system states.

Uses the helper matrices W, Phi_U, and Phi_P to compute H_u and H_p.

Returns:

Containing the matrices H_u and H_p.

Return type:

TPCPredictorMatrices

calculate_regularization_matrices#

do_dpc.dpc.tpc.TPC.calculate_regularization_matrices(self)#

Calculates and returns the regularization matrices for control inputs, states, and outputs.

Uses the helper matrices L and W to compute Lambda_uu, Lambda_uy, and Lambda_uz with regularization terms and system dynamics.

Returns:

Containing the regularization matrices Lambda_uu, Lambda_uy, and Lambda_uz.

Return type:

TPCRegularizationMatrices

get_next_control_action#

do_dpc.dpc.tpc.TPC.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.tpc.TPC.get_predictor_constraint_expression(self)#

Calculates and returns the CVXPY expression for the predictor constraint f.

The predictor constraint is calculated as follows:

\[y_f = H_u u_f + H_p z_p\]
Returns:

The CVXPY constraint for the predictor constraint.

Return type:

cp.constraints.Constraint

Raises:

ValueError – If any matrix in the constraint is not correctly defined.

get_regularization_cost_expression#

do_dpc.dpc.tpc.TPC.get_regularization_cost_expression(self)#

Calculates and returns the CVXPY expression for the regularization cost r.

The regularization cost is calculated as follows:

\[r(u_f, z_p, y_r) = u_f^T \Lambda_{uu} u_f + 2 u_f^T \Lambda_{uz} z_p + 2 u_f^T \Lambda_{uy} y_r\]
Returns:

The CVXPY expression for the regularization cost.

Return type:

cp.Expression

Raises:

Warning – If Lambda_uu is not positive semidefinite.

instantiate#

do_dpc.dpc.tpc.TPC.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.tpc.TPC.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.tpc.TPC.reset_constraints(self)#

Removes all existing constraints from the optimization problem.

Return type:

None

set_state_x#

do_dpc.dpc.tpc.TPC.set_state_x(self, x_new)#

Sets the state (x) for the estimated model.

This method is intended to be overridden by subclasses that have a model, such as MPC variants.

solve#

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

Solves the optimization problem to calculate the optimal control input.

Recommended to use SCS as it does not require a license. MOSEK should be used for better performance if a license is available.

Parameters:

  • verbose (bool) – If True, solver output is displayed.

  • solver (str) – Solver to use (default: SCS).

  • **kwargs – Additional solver parameters.

Raises:

  • ValueError – If the optimization problem is not properly built.

  • ValueError – If the cf_gains are None while using the closed-form solution.

  • RuntimeError – If the solver encounters an issue or produces an infeasible result.

  • Warning – If another solver than Mosek is used.

update_past_measurements#

do_dpc.dpc.tpc.TPC.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.tpc.TPC.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