coneprog
Syntax
Description
The coneprog
function is a second-order cone programming
solver that finds the minimum of a problem specified by
subject to the constraints
f, x, b, beq,
lb, and ub are vectors, and A and
Aeq are matrices. For each i, the matrix
Asc(i), vectors
dsc(i) and
bsc(i), and scalar
γ(i) are in a second-order cone constraint that you
create using secondordercone
.
For more details about cone constraints, see Second-Order Cone Constraint.
solves the second-order cone programming problem with the constraints in
x
= coneprog(f
,socConstraints
)socConstraints
encoded as
Asc(i) =
socConstraints(i).A
bsc(i) =
socConstraints(i).b
dsc(i) =
socConstraints(i).d
γ(i) =
socConstraints(i).gamma
Examples
Single Cone Constraint
To set up a problem with a second-order cone constraint, create a second-order cone constraint object.
A = diag([1,1/2,0]); b = zeros(3,1); d = [0;0;1]; gamma = 0; socConstraints = secondordercone(A,b,d,gamma);
Create an objective function vector.
f = [-1,-2,0];
The problem has no linear constraints. Create empty matrices for these constraints.
Aineq = []; bineq = []; Aeq = []; beq = [];
Set upper and lower bounds on x(3)
.
lb = [-Inf,-Inf,0]; ub = [Inf,Inf,2];
Solve the problem by using the coneprog
function.
[x,fval] = coneprog(f,socConstraints,Aineq,bineq,Aeq,beq,lb,ub)
Optimal solution found.
x = 3×1
0.4851
3.8806
2.0000
fval = -8.2462
The solution component x(3)
is at its upper bound. The cone constraint is active at the solution:
norm(A*x-b) - d'*x % Near 0 when the constraint is active
ans = -2.5677e-08
Several Cone Constraints
To set up a problem with several second-order cone constraints, create an array of constraint objects. To save time and memory, create the highest-index constraint first.
A = diag([1,2,0]); b = zeros(3,1); d = [0;0;1]; gamma = -1; socConstraints(3) = secondordercone(A,b,d,gamma); A = diag([3,0,1]); d = [0;1;0]; socConstraints(2) = secondordercone(A,b,d,gamma); A = diag([0;1/2;1/2]); d = [1;0;0]; socConstraints(1) = secondordercone(A,b,d,gamma);
Create the linear objective function vector.
f = [-1;-2;-4];
Solve the problem by using the coneprog
function.
[x,fval] = coneprog(f,socConstraints)
Optimal solution found.
x = 3×1
0.4238
1.6477
2.3225
fval = -13.0089
Cone Programming with Linear Constraints
Specify an objective function vector and a single second-order cone constraint.
f = [-4;-9;-2]; Asc = diag([1,4,0]); b = [0;0;0]; d = [0;0;1]; gamma = 0; socConstraints = secondordercone(Asc,b,d,gamma);
Specify a linear inequality constraint.
A = [1/4,1/9,1]; b = 5;
Solve the problem.
[x,fval] = coneprog(f,socConstraints,A,b)
Optimal solution found.
x = 3×1
3.2304
0.6398
4.1213
fval = -26.9225
Cone Programming with Nondefault Options
To observe the iterations of the coneprog
solver, set the Display
option to 'iter'
.
options = optimoptions('coneprog','Display','iter');
Create a second-order cone programming problem and solve it using options
.
Asc = diag([1,1/2,0]); b = zeros(3,1); d = [0;0;1]; gamma = 0; socConstraints = secondordercone(Asc,b,d,gamma); f = [-1,-2,0]; Aineq = []; bineq = []; Aeq = []; beq = []; lb = [-Inf,-Inf,0]; ub = [Inf,Inf,2]; [x,fval] = coneprog(f,socConstraints,Aineq,bineq,Aeq,beq,lb,ub,options)
Iter Fval Primal Infeas Dual Infeas Duality Gap Time 0 0.000000e+00 0.000000e+00 5.714286e-01 2.000000e-01 0.05 1 -7.558066e+00 0.000000e+00 7.151114e-02 2.502890e-02 0.13 2 -7.366973e+00 0.000000e+00 1.075440e-02 3.764040e-03 0.14 3 -8.243432e+00 0.000000e+00 5.191882e-05 1.817159e-05 0.14 4 -8.246067e+00 0.000000e+00 2.430813e-06 8.507845e-07 0.14 5 -8.246211e+00 0.000000e+00 6.154504e-09 2.154077e-09 0.14 Optimal solution found.
x = 3×1
0.4851
3.8806
2.0000
fval = -8.2462
Cone Programming with Problem Structure
Create the elements of a second-order cone programming problem. To save time and memory, create the highest-index constraint first.
A = diag([1,2,0]); b = zeros(3,1); d = [0;0;1]; gamma = -1; socConstraints(3) = secondordercone(A,b,d,gamma); A = diag([3,0,1]); d = [0;1;0]; socConstraints(2) = secondordercone(A,b,d,gamma); A = diag([0;1/2;1/2]); d = [1;0;0]; socConstraints(1) = secondordercone(A,b,d,gamma); f = [-1;-2;-4]; options = optimoptions('coneprog','Display','iter');
Create a problem structure with the required fields, as described in problem.
problem = struct('f',f,... 'socConstraints',socConstraints,... 'Aineq',[],'bineq',[],... 'Aeq',[],'beq',[],... 'lb',[],'ub',[],... 'solver','coneprog',... 'options',options);
Solve the problem by calling coneprog
.
[x,fval] = coneprog(problem)
Iter Fval Primal Infeas Dual Infeas Duality Gap Time 0 0.000000e+00 0.000000e+00 5.333333e-01 9.090909e-02 0.02 1 -9.696012e+00 5.551115e-17 7.631901e-02 1.300892e-02 0.03 2 -1.178942e+01 0.000000e+00 1.261803e-02 2.150800e-03 0.03 3 -1.294426e+01 9.251859e-18 1.683078e-03 2.868883e-04 0.03 4 -1.295217e+01 9.251859e-18 8.994595e-04 1.533170e-04 0.03 5 -1.295331e+01 0.000000e+00 4.748841e-04 8.094615e-05 0.03 6 -1.300753e+01 0.000000e+00 2.799942e-05 4.772628e-06 0.03 7 -1.300671e+01 9.251859e-18 2.366136e-05 4.033187e-06 0.03 8 -1.300850e+01 9.251859e-18 8.251573e-06 1.406518e-06 0.03 9 -1.300842e+01 4.625929e-18 7.332583e-06 1.249872e-06 0.04 10 -1.300866e+01 9.251859e-18 2.616719e-06 4.460317e-07 0.04 11 -1.300892e+01 1.850372e-17 2.215835e-08 3.776991e-09 0.04 Optimal solution found.
x = 3×1
0.4238
1.6477
2.3225
fval = -13.0089
Examine coneprog
Solution Process
Create a second-order cone programming problem. To save time and memory, create the highest-index constraint first.
A = diag([1,2,0]); b = zeros(3,1); d = [0;0;1]; gamma = -1; socConstraints(3) = secondordercone(A,b,d,gamma); A = diag([3,0,1]); d = [0;1;0]; socConstraints(2) = secondordercone(A,b,d,gamma); A = diag([0;1/2;1/2]); d = [1;0;0]; socConstraints(1) = secondordercone(A,b,d,gamma); f = [-1;-2;-4]; options = optimoptions('coneprog','Display','iter'); A = []; b = []; Aeq = []; beq = []; lb = []; ub = [];
Solve the problem, requesting information about the solution process.
[x,fval,exitflag,output] = coneprog(f,socConstraints,A,b,Aeq,beq,lb,ub,options)
Iter Fval Primal Infeas Dual Infeas Duality Gap Time 0 0.000000e+00 0.000000e+00 5.333333e-01 9.090909e-02 0.08 1 -9.696012e+00 5.551115e-17 7.631901e-02 1.300892e-02 0.10 2 -1.178942e+01 0.000000e+00 1.261803e-02 2.150800e-03 0.10 3 -1.294426e+01 9.251859e-18 1.683078e-03 2.868883e-04 0.10 4 -1.295217e+01 9.251859e-18 8.994595e-04 1.533170e-04 0.11 5 -1.295331e+01 0.000000e+00 4.748841e-04 8.094615e-05 0.11 6 -1.300753e+01 0.000000e+00 2.799942e-05 4.772628e-06 0.11 7 -1.300671e+01 9.251859e-18 2.366136e-05 4.033187e-06 0.11 8 -1.300850e+01 9.251859e-18 8.251573e-06 1.406518e-06 0.11 9 -1.300842e+01 4.625929e-18 7.332583e-06 1.249872e-06 0.11 10 -1.300866e+01 9.251859e-18 2.616719e-06 4.460317e-07 0.11 11 -1.300892e+01 1.850372e-17 2.215835e-08 3.776991e-09 0.11 Optimal solution found.
x = 3×1
0.4238
1.6477
2.3225
fval = -13.0089
exitflag = 1
output = struct with fields:
iterations: 11
primalfeasibility: 1.8504e-17
dualfeasibility: 2.2158e-08
dualitygap: 3.7770e-09
algorithm: 'interior-point'
linearsolver: 'augmented'
message: 'Optimal solution found.'
Both the iterative display and the output structure show that
coneprog
used 12 iterations to arrive at the solution.The exit flag value
1
and theoutput.message
value'Optimal solution found.'
indicate that the solution is reliable.The
output
structure shows that the infeasibilities tend to decrease through the solution process, as does the duality gap.You can reproduce the
fval
output by multiplyingf'*x
.
f'*x
ans = -13.0089
Obtain coneprog
Dual Variables
Create a second-order cone programming problem. To save time and memory, create the highest-index constraint first.
A = diag([1,2,0]); b = zeros(3,1); d = [0;0;1]; gamma = -1; socConstraints(3) = secondordercone(A,b,d,gamma); A = diag([3,0,1]); d = [0;1;0]; socConstraints(2) = secondordercone(A,b,d,gamma); A = diag([0;1/2;1/2]); d = [1;0;0]; socConstraints(1) = secondordercone(A,b,d,gamma); f = [-1;-2;-4];
Solve the problem, requesting dual variables at the solution along with all other coneprog
output..
[x,fval,exitflag,output,lambda] = coneprog(f,socConstraints);
Optimal solution found.
Examine the returned lambda
structure. Because the only problem constraints are cone constraints, examine only the soc
field in the lambda
structure.
disp(lambda.soc)
5.9426 4.6039 2.4624
The constraints have nonzero dual values, indicating the constraints are active at the solution.
Input Arguments
f
— Coefficient vector
real vector | real array
Coefficient vector, specified as a real vector or real array. The coefficient vector
represents the objective function f'*x
. The notation assumes that
f
is a column vector, but you can use a row vector or array.
Internally, coneprog
converts f
to the column
vector f(:)
.
Example: f = [1,3,5,-6]
Data Types: double
socConstraints
— Second-order cone constraints
vector of SecondOrderConeConstraint
objects | cell array of SecondOrderConeConstraint
objects
Second-order cone constraints, specified as vector or cell array of SecondOrderConeConstraint
objects. Create these objects using the secondordercone
function.
socConstraints
encodes the constraints
where the mapping between the array and the equation is as follows:
Asc(i) =
socConstraints.A(i)
bsc(i) =
socConstraints.b(i)
dsc(i) =
socConstraints.d(i)
γ(i) =
socConstraints.gamma(i)
Example: Asc = diag([1 1/2 0]); bsc = zeros(3,1); dsc = [0;0;1]; gamma = -1;
socConstraints = secondordercone(Asc,bsc,dsc,gamma);
A
— Linear inequality constraints
real matrix
Linear inequality constraints, specified as a real matrix. A
is an M
-by-N
matrix, where M
is the number of inequalities, and N
is the number of variables (length of f
). For large problems, pass A
as a sparse matrix.
A
encodes the M
linear inequalities
A*x <= b
,
where x
is the column vector of N
variables x(:)
, and b
is a column vector with M
elements.
For example, consider these inequalities:
x1 +
2x2 ≤
10
3x1 +
4x2 ≤
20
5x1 +
6x2 ≤ 30.
Specify the inequalities by entering the following constraints.
A = [1,2;3,4;5,6]; b = [10;20;30];
Example: To specify that the x-components add up to 1 or less, take A =
ones(1,N)
and b = 1
.
Data Types: double
b
— Linear inequality constraints
real vector
Linear inequality constraints, specified as a real vector. b
is
an M
-element vector related to the A
matrix.
If you pass b
as a row vector, solvers internally
convert b
to the column vector b(:)
.
For large problems, pass b
as a sparse vector.
b
encodes the M
linear
inequalities
A*x <= b
,
where x
is the column vector of N
variables x(:)
,
and A
is a matrix of size M
-by-N
.
For example, consider these inequalities:
x1
+ 2x2 ≤
10
3x1
+ 4x2 ≤
20
5x1
+ 6x2 ≤
30.
Specify the inequalities by entering the following constraints.
A = [1,2;3,4;5,6]; b = [10;20;30];
Example: To specify that the x components sum to 1 or less, use A =
ones(1,N)
and b = 1
.
Data Types: single
| double
Aeq
— Linear equality constraints
real matrix
Linear equality constraints, specified as a real matrix. Aeq
is an Me
-by-N
matrix, where Me
is the number of equalities, and N
is the number of variables (length of f
). For large problems, pass Aeq
as a sparse matrix.
Aeq
encodes the Me
linear equalities
Aeq*x = beq
,
where x
is the column vector of N
variables x(:)
, and beq
is a column vector with Me
elements.
For example, consider these equalities:
x1 +
2x2 +
3x3 =
10
2x1 +
4x2 +
x3 = 20.
Specify the equalities by entering the following constraints.
Aeq = [1,2,3;2,4,1]; beq = [10;20];
Example: To specify that the x-components sum to 1, take Aeq = ones(1,N)
and
beq = 1
.
Data Types: double
beq
— Linear equality constraints
real vector
Linear equality constraints, specified as a real vector. beq
is
an Me
-element vector related to the Aeq
matrix.
If you pass beq
as a row vector, solvers internally
convert beq
to the column vector beq(:)
.
For large problems, pass beq
as a sparse vector.
beq
encodes the Me
linear
equalities
Aeq*x = beq
,
where x
is the column vector of N
variables
x(:)
, and Aeq
is a matrix of size
Me
-by-N
.
For example, consider these equalities:
x1
+ 2x2 +
3x3 =
10
2x1
+ 4x2 +
x3 =
20.
Specify the equalities by entering the following constraints.
Aeq = [1,2,3;2,4,1]; beq = [10;20];
Example: To specify that the x components sum to 1, use Aeq = ones(1,N)
and
beq = 1
.
Data Types: single
| double
lb
— Lower bounds
real vector | real array
Lower bounds, specified as a real vector or real array. If the length of
f
is equal to the length of lb
, then
lb
specifies that
x(i) >= lb(i)
for all i
.
If numel(lb) < numel(f)
, then lb
specifies that
x(i) >= lb(i)
for 1 <= i <= numel(lb)
.
In this case, solvers issue a warning.
Example: To specify that all x-components are positive, use lb =
zeros(size(f))
.
Data Types: double
ub
— Upper bounds
real vector | real array
Upper bounds, specified as a real vector or real array. If the length of
f
is equal to the length of ub
, then
ub
specifies that
x(i) <= ub(i)
for all i
.
If numel(ub) < numel(f)
, then ub
specifies that
x(i) <= ub(i)
for 1 <= i <= numel(ub)
.
In this case, solvers issue a warning.
Example: To specify that all x-components are less than 1
, use ub =
ones(size(f))
.
Data Types: double
options
— Optimization options
output of optimoptions
Optimization options, specified as the output of
optimoptions
.
MATLAB Options | |
---|---|
Option | Description |
ConstraintTolerance | Feasibility tolerance for constraints, a nonnegative scalar.
|
| Level of display (see Iterative Display):
|
LinearSolver | Algorithm for solving one step in the iteration:
If
For a sparse example, see Compare Speeds of coneprog Algorithms. |
| Maximum number of iterations allowed, a nonnegative integer. The
default is See Tolerances and Stopping Criteria and Iterations and Function Counts. |
MaxTime | Maximum amount of time in seconds that the algorithm runs, a
nonnegative number or |
| Termination tolerance on the dual feasibility, a nonnegative scalar.
The default is |
Code Generation | |
ConstraintTolerance | Feasibility tolerance for constraints, a nonnegative scalar.
|
| Level of display (see Iterative Display):
Iterative display does not show a column for time in generated code. |
LinearSolver | Algorithm for solving one step in the iteration: For code generation, there is a limited set of choices of
|
| Maximum number of iterations allowed, a nonnegative integer. The
default is See Tolerances and Stopping Criteria and Iterations and Function Counts. |
| Termination tolerance on the dual feasibility, a nonnegative scalar.
The default is |
Code generation does not support the MaxTime
option.
Example: optimoptions("coneprog",Display="iter",MaxIterations=100)
problem
— Problem structure
structure
Problem structure, specified as a structure with the following fields.
Field Name | Entry |
---|---|
| Linear objective function vector f |
| Structure array of second-order cone constraints |
| Matrix of linear inequality constraints |
| Vector of linear inequality constraints |
| Matrix of linear equality constraints |
| Vector of linear equality constraints |
lb | Vector of lower bounds |
ub | Vector of upper bounds |
| 'coneprog' |
| Options created with optimoptions |
Data Types: struct
Output Arguments
fval
— Objective function value at the solution
real number
Objective function value at the solution, returned as a real number. Generally,
fval
= f'*x
. The fval
output
is empty (NaN
for code generation) when the
exitflag
value is –2
, –3
,
or –10
.
exitflag
— Reason coneprog
stopped
integer
Reason coneprog
stopped, returned as an integer.
Value | Description |
---|---|
| The function converged to a solution
|
| The number of iterations exceeded
|
| No feasible point was found. |
| The problem is unbounded. |
| The search direction became too small. No further progress could be made. |
| The problem is numerically unstable. |
Tip
If you get exit flag 0
, -7
, or
-10
, try using a different value of the
LinearSolver
option.
output
— Information about optimization process
structure
Information about the optimization process, returned as a structure with these fields.
Field | Description |
---|---|
algorithm |
|
dualfeasibility | Maximum of dual constraint violations |
dualitygap | Duality gap |
iterations | Number of iterations |
message | Exit message — not available in code generation |
primalfeasibility | Maximum of constraint violations |
linearsolver | Internal step solver algorithm used |
The output
fields algorithm
,
dualfeasibility
, dualitygap
,
linearsolver
, and primalfeasibility
are empty
(numeric values are NaN
for code generation) when the
exitflag
value is –2, –3, or –10.
The iterations
field has int32
type for code
generation, not double.
lambda
— Dual variables at the solution
structure
Dual variables at the solution, returned as a structure with these fields.
Field | Description |
---|---|
lower | Lower bounds corresponding to |
upper | Upper bounds corresponding to |
ineqlin | |
eqlin | |
soc | Second-order cone constraints corresponding to
socConstraints |
lambda
is empty ([]
) when the
exitflag
value is –2
, –3
,
or –10
.
The Lagrange multipliers (dual variables) are part of the following Lagrangian, which is stationary (zero gradient) at a solution:
More About
Second-Order Cone Constraint
Why is the constraint
called a second-order cone constraint? Consider a cone in 3-D space with elliptical cross-sections in the x-y plane, and a diameter proportional to the z coordinate. The y coordinate has scale ½, and the x coordinate has scale 1. The inequality defining the inside of this cone with its point at [0,0,0] is
In the coneprog
syntax, this cone has the following
arguments.
A = diag([1 1/2 0]); b = [0;0;0]; d = [0;0;1]; gamma = 0;
Plot the boundary of the cone.
[X,Y] = meshgrid(-2:0.1:2); Z = sqrt(X.^2 + Y.^2/4); surf(X,Y,Z) view(8,2) xlabel 'x' ylabel 'y' zlabel 'z'
The b
and gamma
arguments move the cone. The
A
and d
arguments rotate the cone and change its
shape.
Algorithms
The algorithm uses an interior-point method. For details, see Second-Order Cone Programming Algorithm.
Alternative Functionality
App
The Optimize Live Editor task provides a visual interface for coneprog
.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
coneprog
supports code generation using either thecodegen
(MATLAB Coder) function or the MATLAB® Coder™ app. You must have a MATLAB Coder license to generate code.The target hardware must support standard double-precision floating-point computations.
Code generation targets do not use the same math kernel libraries as MATLAB solvers. Therefore, code generation solutions can vary from solver solutions, especially for poorly conditioned problems.
coneprog
does not support theproblem
argument for code generation.[x,fval] = coneprog(problem) % Not supported
All
coneprog
input matrices such asA
,Aeq
,lb
, andub
must be full, not sparse. You can convert sparse matrices to full by using thefull
function.Pass cone constraints as a cell array of
SecondOrderConeConstraint
objects, not as an array of these objects. If you have no cone constraints, pass an empty cell{}
.The
lb
andub
arguments must have the same number of entries as the number of problem variables or must be empty[]
.If your target hardware does not support infinite bounds, use
optim.coder.infbound
.For advanced code optimization involving embedded processors, you also need an Embedded Coder® license.
Code generation supports these options using
optimoptions
:ConstraintTolerance
Display
LinearSolver
MaxIterations
OptimalityTolerance
Generated code has limited error checking for options. The recommended way to update an option is to use dot notation, not
optimoptions
.opts = optimoptions("coneprog",ConstraintTolerance=1e-4); opts = optimoptions(opts,MaxIterations=1e4); % Not supported opts.MaxIterations = 1e4; % Recommended
coneprog
supports options passed into the solver, not only options created in the code.If you specify an option that is not supported, the option is typically ignored during code generation. For reliable results, specify only supported options.
Version History
Introduced in R2020bR2024b: Code generation
coneprog
can generate C/C++ code. For details, see Code Generation for coneprog Background and Generate Code for coneprog. To accommodate code
generation, you can now pass second order cone constraints as a cell array of SecondOrderConeConstraint
objects, and this is the required syntax for code
generation. See Language Limitations (MATLAB Coder).
R2024a: 'normal-dense'
linear solver for increased speed in dense problems
To gain speed in problems with dense data, set the LinearSolver
option to 'normal-dense'
. For an example, see Compare Speeds of coneprog Algorithms.
R2021a: Two coneprog
lambda
Structures Renamed
The coneprog
lambda
output
argument fields lambda.eq
and lambda.ineq
have been
renamed to lambda.eqlin
and lambda.ineqlin
,
respectively. This change causes the coneprog
lambda
structure fields to have the same names as the corresponding
fields in other solvers.
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)