ADMM

Options object for active set QP solver used in mpc object

Since R2024a

Description

Use the ADMM object to set options for the active-set QP solver used within an mpc object.

Creation

Creating an mpc object automatically creates an ADMM object set to default options. If the Optimizer.Solver property of the mpc object is set to "admm", the ADMM object is assigned to the Optimizer.SolverOption property of the mpc object. You can access the object and its properties using dot notation.

Properties

AbsoluteTolerance — Absolute tolerance

1e-4 (default) | positive scalar

Absolute tolerance, specified as a positive scalar. This tolerance sets the allowable absolute error between the primal and dual feasibility conditions.

Example: mpcobj.Optimizer.SolverOptions.AbsoluteTolerance = 1e-5

RelativeTolerance — Relative tolerance

1e-4 (default) | positive scalar

Relative tolerance, specified as a positive scalar. This tolerance sets the allowed error relative to the largest component of the solution.

Example: mpcobj.Optimizer.SolverOptions.RelativeTolerance = 1e-5

MaxIterations — Maximum number of iterations

1000 (default) | positive integer

Maximum number of iterations allowed during the computation of the solution, specified as a positive integer. The QP solver stops after the specified number of iterations. If the solver fails to converge in the final iteration, the controller:

• Freezes the controller movement if UseSuboptimalSolution is false.

• Applies the suboptimal solution reached after the final iteration if UseSuboptimalSolution is true.

Example: mpcobj.Optimizer.SolverOptions.MaxIterations = 500

RelaxationParameter — Relaxation parameter

1 (default) | positive scalar

Relaxation parameter, specified as a positive scalar. This parameter is typically referred to as α in the ADMM literature, and it regularizes the update of the primal variable. A positive value can help to speed up convergence. For more information, see [1].

Example: mpcobj.Optimizer.SolverOptions.RelaxationParameter = 1e-5

PenaltyParameter — Penalty parameter

1.6 (default) | positive scalar

Penalty parameter, specified as a positive scalar. This parameter is typically referred to as ρ in the ADMM literature, and it inversely weights the importance of the perturbation on the update of the intermediate variable. For more information, see [1].

Example: mpcobj.Optimizer.SolverOptions.PenaltyParameter = 0.8

StepSize — Step size parameter

1e-6 (default) | positive scalar

Step size parameter, specified as a positive scalar. This parameter is typically referred to as σ in the ADMM literature. A larger value allows for a better numerical conditioning of the hessian matrix, therefore increasing numerical stability. However, a value that is too large can result in longer convergence times, as the solver might need to perform more iterations to reach the desired terminal tolerances. For more information, see [1].

Example: mpcobj.Optimizer.SolverOptions.StepSize = 1e-5

Object Functions

Examples

Access Properties of ADMM Options Object

Create an mpc object.

plant = ss(0.8,0.5,0.25,0,0.1); 
mpcobj=mpc(plant);

-->"PredictionHorizon" is empty. Assuming default 10.
-->"ControlHorizon" is empty. Assuming default 2.
-->"Weights.ManipulatedVariables" is empty. Assuming default 0.00000.
-->"Weights.ManipulatedVariablesRate" is empty. Assuming default 0.10000.
-->"Weights.OutputVariables" is empty. Assuming default 1.00000.

Display the fields of the Optimizer property.

mpcobj.Optimizer

ans = struct with fields:
         OptimizationType: 'QP'
                   Solver: 'active-set'
            SolverOptions: [1×1 mpc.solver.options.qp.ActiveSet]
             MinOutputECR: 0
    UseSuboptimalSolution: 0
             CustomSolver: 0
      CustomSolverCodeGen: 0

Set the solver property to "admm".

mpcobj.Optimizer.Solver = "admm";

Display the properties of the SolverOptions object.

mpcobj.Optimizer.SolverOptions

ans = 
  ADMM with properties:

      AbsoluteTolerance: 1.0000e-04
      RelativeTolerance: 1.0000e-04
          MaxIterations: 1000
    RelaxationParameter: 1
       PenaltyParameter: 1.6000
               StepSize: 1.0000e-06

Modify the RelativeTolerance property.

mpcobj.Optimizer.SolverOptions.RelativeTolerance = 2e-4;

Extract the object.

adopts = mpcobj.Optimizer.SolverOptions;

Modify the MaxIterations property.

adopts.MaxIterations = 500;

Reassign the object to the SolverOptions field of the Optimizer property of mpcobj.

mpcobj.Optimizer.SolverOptions = adopts;

Display the fields of the Optimizer property again.

mpcobj.Optimizer.SolverOptions

ans = 
  ADMM with properties:

      AbsoluteTolerance: 1.0000e-04
      RelativeTolerance: 2.0000e-04
          MaxIterations: 500
    RelaxationParameter: 1
       PenaltyParameter: 1.6000
               StepSize: 1.0000e-06

References

[1] Boyd, Stephen, Neal Parikh, Eric Chu, Borja Peleato and Jonathan Eckstein. “Distributed Optimization and Statistical Learning via the Alternating Direction Method of Multipliers.” Foundations and Trends® in Machine Learning 3, no. 1 (2010): 1–122. https://doi.org/10.1561/2200000016.

Version History

Introduced in R2024a