ADMM

R2026b

Options object for ADMM 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.

Note

The solver terminates when either of the following conditions is met:

• The maximum number of iterations (MaxIterations) is reached

• The maximum allowed elapsed time (MaxTime) has been exceeded.

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.

Using MaxTime for code generation is supported.

Example: mpcobj.Optimizer.SolverOptions.MaxIterations = 500

MaxTime — Maximum wall-clock execution time allowed to the solver

inf (default) | positive scalar | duration object

Maximum wall-clock execution time allowed to the solver, specified as a positive scalar (in seconds) or as a scalar duration object. By default, this property is set to Inf.

Note

The solver terminates when either of the following conditions is met:

• The maximum number of iterations (MaxIterations) is reached.

• The maximum allowed elapsed time (MaxTime) is exceeded.

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.Maxtime = seconds(0.02)

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

PrimalInfeasibilityTolerance — Primal infeasibility tolerance

1e-4 (default) | positive scalar

Primal infeasibility tolerance, specified as a positive scalar. This tolerance sets the level for detecting infeasibility of the primal QP problem.

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

DualInfeasibilityTolerance — Dual infeasibility tolerance

1e-4 (default) | positive scalar

Dual infeasibility tolerance, specified as a positive scalar. This tolerance sets the level for detecting infeasibility of the dual QP problem.

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

EnablePolish — Enable solution polish

false (default) | true

Option to enable a solution refinement phase after the main ADMM iterations. Polishing can improve the accuracy of the solution.

Example: mpcobj.Optimizer.SolverOptions.EnablePolish = true

PolishRegularization — Polish regularization parameter

1e-6 (default) | positive scalar

Polish regularization parameter, specified as a positive scalar. This is a regularization parameter used during the solution of refinement phase to improve accuracy.

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

PolishTolerance — Polish tolerance

1e-8 (default) | positive scalar

Polish tolerance, specified as a positive scalar. This is the tolerance used during the solution refinement phase to improve accuracy.

Example: mpcobj.Optimizer.SolverOptions.PolishTolerance = 1e-7

PolishMaxIterations — Maximum number of iterations for the solution refinement phase

3 (default) | positive integer

Maximum number of iterations allowed during the solution refinement phase, specified as a positive integer.

Example: mpcobj.Optimizer.SolverOptions.PolishMaxIterations = 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-03
               RelativeTolerance: 1.0000e-03
                   MaxIterations: 1000
                         MaxTime: Inf sec
             RelaxationParameter: 1.6000
                PenaltyParameter: 0.1000
                        StepSize: 1.0000e-06
    PrimalInfeasibilityTolerance: 1.0000e-04
      DualInfeasibilityTolerance: 1.0000e-04
                    EnablePolish: 0
            PolishRegularization: 1.0000e-06
                 PolishTolerance: 1.0000e-08
             PolishMaxIterations: 3

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-03
               RelativeTolerance: 2.0000e-04
                   MaxIterations: 500
                         MaxTime: Inf sec
             RelaxationParameter: 1.6000
                PenaltyParameter: 0.1000
                        StepSize: 1.0000e-06
    PrimalInfeasibilityTolerance: 1.0000e-04
      DualInfeasibilityTolerance: 1.0000e-04
                    EnablePolish: 0
            PolishRegularization: 1.0000e-06
                 PolishTolerance: 1.0000e-08
             PolishMaxIterations: 3

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