prob2struct
Convert optimization problem or equation problem to solver form
Syntax
Description
Use prob2struct
to convert an optimization problem or
equation problem to solver form.
Tip
For the full workflow, see ProblemBased Optimization Workflow or ProblemBased Workflow for Solving Equations.
,
for any input arguments, specifies additional options using one or more namevalue
pair arguments. For example, for a nonlinear optimization problem, problem
= prob2struct(___,Name,Value
)problem
= prob2struct(prob,'ObjectiveFunctionName','objfun1')
specifies that
prob2struct
creates an objective function file named
objfun1.m
in the current folder.
Examples
Convert Problem to Structure
Convert an optimization problem object to a problem structure.
Input the basic MILP problem from MixedInteger Linear Programming Basics: ProblemBased.
ingots = optimvar('ingots',4,1,'Type','integer','LowerBound',0,'UpperBound',1); alloys = optimvar('alloys',4,1,'LowerBound',0); weightIngots = [5,3,4,6]; costIngots = weightIngots.*[350,330,310,280]; costAlloys = [500,450,400,100]; cost = costIngots*ingots + costAlloys*alloys; steelprob = optimproblem; steelprob.Objective = cost; totalweight = weightIngots*ingots + sum(alloys); carbonIngots = [5,4,5,3]/100; molybIngots = [3,3,4,4,]/100; carbonAlloys = [8,7,6,3]/100; molybAlloys = [6,7,8,9]/100; totalCarbon = (weightIngots.*carbonIngots)*ingots + carbonAlloys*alloys; totalMolyb = (weightIngots.*molybIngots)*ingots + molybAlloys*alloys; steelprob.Constraints.conswt = totalweight == 25; steelprob.Constraints.conscarb = totalCarbon == 1.25; steelprob.Constraints.consmolyb = totalMolyb == 1.25;
Convert the problem to an intlinprog
problem structure.
problem = prob2struct(steelprob);
Examine the resulting linear equality constraint matrix and vector.
Aeq = problem.Aeq
Aeq = (1,1) 1.0000 (2,1) 0.0800 (3,1) 0.0600 (1,2) 1.0000 (2,2) 0.0700 (3,2) 0.0700 (1,3) 1.0000 (2,3) 0.0600 (3,3) 0.0800 (1,4) 1.0000 (2,4) 0.0300 (3,4) 0.0900 (1,5) 5.0000 (2,5) 0.2500 (3,5) 0.1500 (1,6) 3.0000 (2,6) 0.1200 (3,6) 0.0900 (1,7) 4.0000 (2,7) 0.2000 (3,7) 0.1600 (1,8) 6.0000 (2,8) 0.1800 (3,8) 0.2400
beq = problem.beq
beq = 3×1
25.0000
1.2500
1.2500
Examine the bounds.
problem.lb
ans = 8×1
0
0
0
0
0
0
0
0
problem.ub
ans = 8×1
Inf
Inf
Inf
Inf
1
1
1
1
Solve the problem by calling intlinprog
.
x = intlinprog(problem)
LP: Optimal objective value is 8125.600000. Cut Generation: Applied 3 mir cuts. Lower bound is 8495.000000. Relative gap is 0.00%. Optimal solution found. Intlinprog stopped at the root node because the objective value is within a gap tolerance of the optimal value, options.AbsoluteGapTolerance = 0 (the default value). The intcon variables are integer within tolerance, options.IntegerTolerance = 1e05 (the default value).
x = 8×1
7.2500
0
0.2500
3.5000
1.0000
1.0000
0
1.0000
Convert Nonlinear Problem to Structure
Create a nonlinear problem in the problembased framework.
x = optimvar('x',2); fun = 100*(x(2)  x(1)^2)^2 + (1  x(1))^2; prob = optimproblem('Objective',fun); mycon = dot(x,x) <= 4; prob.Constraints.mycon = mycon; x0.x = [1;1.5];
Convert prob
to an optimization problem structure. Name the generated objective function file 'rosenbrock'
and the constraint function file 'circle2'
.
problem = prob2struct(prob,x0,'ObjectiveFunctionName','rosenbrock',... 'ConstraintFunctionName','circle2');
prob2struct
creates nonlinear objective and constraint function files in the current folder. To create these files in a different folder, use the 'FileLocation'
namevalue pair.
Solve the problem.
[x,fval] = fmincon(problem)
Local minimum found that satisfies the constraints. Optimization completed because the objective function is nondecreasing in feasible directions, to within the value of the optimality tolerance, and constraints are satisfied to within the value of the constraint tolerance.
x = 2×1
1.0000
1.0000
fval = 4.6187e11
Input Arguments
prob
— Optimization problem or equation problem
OptimizationProblem
object  EquationProblem
object
Optimization problem or equation problem, specified as an OptimizationProblem
object or an EquationProblem
object. Create an optimization problem by using optimproblem
; create an equation problem by using eqnproblem
.
Warning
The problembased approach does not support complex values in an objective function, nonlinear equalities, or nonlinear inequalities. If a function calculation has a complex value, even as an intermediate value, the final result can be incorrect.
Example: prob = optimproblem; prob.Objective = obj; prob.Constraints.cons1 =
cons1;
Example: prob = eqnproblem; prob.Equations = eqs;
x0
— Initial point
structure  vector of OptimizationValues
objects
Initial point, specified as a structure with field names equal to the variable names in prob
.
For some Global Optimization Toolbox solvers, x0
can be a vector of OptimizationValues
objects representing multiple initial points. Create
the points using the optimvalues
function. These solvers are:
ga
(Global Optimization Toolbox),gamultiobj
(Global Optimization Toolbox),paretosearch
(Global Optimization Toolbox) andparticleswarm
(Global Optimization Toolbox). These solvers accept multiple starting points as members of the initial population.MultiStart
(Global Optimization Toolbox). This solver accepts multiple initial points for a local solver such asfmincon
.surrogateopt
(Global Optimization Toolbox). This solver accepts multiple initial points to help create an initial surrogate.
For an example using x0
with named index variables, see Create Initial Point for Optimization with Named Index Variables.
Example: If prob
has variables named x
and y
: x0.x = [3,2,17]; x0.y = [pi/3,2*pi/3]
.
Data Types: struct
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: problem =
prob2struct(prob,'FileLocation','C:\Documents\myproblem')
ConstraintDerivative
— Indication to use automatic differentiation for constraint functions
'auto'
(default)  'autoforward'
 'autoreverse'
 'finitedifferences'
Indication to use automatic differentiation (AD) for nonlinear
constraint functions, specified as the commaseparated pair consisting
of 'ConstraintDerivative'
and
'auto'
(use AD if possible),
'autoforward'
(use forward AD if possible),
'autoreverse'
(use reverse AD if possible), or
'finitedifferences'
(do not use AD). Choices
including auto
cause the resulting constraint
function file to use gradient information when solving the problem
provided that the constraint functions are supported, as described in
Supported Operations for Optimization Variables and Expressions. For
an example, see Supply Derivatives in ProblemBased Workflow
Note
To use automatic derivatives in a problem converted by prob2struct
, pass options specifying these derivatives.
options = optimoptions('fmincon','SpecifyObjectiveGradient',true,... 'SpecifyConstraintGradient',true); problem.options = options;
Example: 'finitedifferences'
Data Types: char
 string
ConstraintFunctionName
— Name of nonlinear constraint function file
'generatedConstraints'
(default)  file name
Name of the nonlinear constraint function file created by
prob2struct
for an optimization problem,
specified as the commaseparated pair consisting of
'ConstraintFunctionName'
and a file name. This
argument applies to fmincon
or
fminunc
problems; see problem
. Do not include the file extension
.m
in the file name.
prob2struct
appends the file extension when it
creates the file.
If you do not specify ConstraintFunctionName
, then
prob2struct
overwrites
'generatedConstraints.m'
. If you do not specify
FileLocation
, then
prob2struct
creates the file in the current
folder.
The returned problem
structure refers to this
function file.
Example: "mynlcons"
Data Types: char
 string
EquationFunctionName
— Name of equation function file
'generatedEquation'
(default)  file name
Name of the nonlinear equation function file created by
prob2struct
for an equation problem, specified
as the commaseparated pair consisting of
'EquationFunctionName'
and a file name. This
argument applies to fsolve
,
fzero
, or lsqnonlin
equations; see problem
. Do not include the file extension
.m
in the file name.
prob2struct
appends the file extension when it
creates the file.
If you do not specify EquationFunctionName
, then
prob2struct
overwrites
'generatedEquation.m'
. If you do not specify
FileLocation
, then
prob2struct
creates the file in the current
folder.
The returned problem
structure refers to this
function file.
Example: "myequation"
Data Types: char
 string
FileLocation
— Location for generated files
current folder (default)  path to a writable folder
Location for generated files (objective function, constraint function,
and other subfunction files), specified as the commaseparated pair
consisting of 'FileLocation'
and a path to a writable
folder. All the generated files are stored in this folder; multiple
folders are not supported.
Example: 'C:Documents\MATLAB\myproject'
Data Types: char
 string
ObjectiveDerivative
— Indication to use automatic differentiation for objective function
'auto'
(default)  'autoforward'
 'autoreverse'
 'finitedifferences'
Indication to use automatic differentiation (AD) for nonlinear
objective function, specified as the commaseparated pair consisting of
'ObjectiveDerivative'
and
'auto'
(use AD if possible),
'autoforward'
(use forward AD if possible),
'autoreverse'
(use reverse AD if possible), or
'finitedifferences'
(do not use AD). Choices
including auto
cause the resulting objective function
file to include derivative information when solving the problem provided
that the objective function is supported, as described in Supported Operations for Optimization Variables and Expressions. For
an example, see Supply Derivatives in ProblemBased Workflow.
Note
To use automatic derivatives in a problem converted by prob2struct
, pass options specifying these derivatives.
options = optimoptions('fmincon','SpecifyObjectiveGradient',true,... 'SpecifyConstraintGradient',true); problem.options = options;
Example: 'finitedifferences'
Data Types: char
 string
ObjectiveFunctionName
— Name of objective function file
'generatedObjective'
(default)  file name
Name of the objective function file created by
prob2struct
for an optimization problem,
specified as the commaseparated pair consisting of
'ObjectiveFunctionName'
and a file name. This
argument applies to fmincon
or
fminunc
problems; see problem
. Do not include the file extension
.m
in the file name.
prob2struct
appends the file extension when it
creates the file.
If you do not specify ObjectiveFunctionName
, then
prob2struct
overwrites
'generatedObjective.m'
. If you do not specify
FileLocation
, then
prob2struct
creates the file in the current
folder.
The returned problem
structure refers to this
function file.
Example: "myobj"
Data Types: char
 string
Solver
— Optimization solver
'intlinprog'
 'linprog'
 'lsqlin'
 'lsqcurvefit'
 'lsqnonlin'
 'lsqnonneg'
 'quadprog'
 'fminunc'
 'fmincon'
 'fzero'
 'fsolve'
 'coneprog'
 'ga'
 'gamultiobj'
 'paretosearch'
 'patternsearch'
 'particleswarm'
 'surrogateopt'
 'simulannealbnd'
Optimization solver, specified as the name of a listed solver. For optimization problems, this table contains the available solvers for each problem type, including solvers from Global Optimization Toolbox. Details for equation problems appear below the optimization solver details.
For converting nonlinear problems with integer constraints using
prob2struct
, the resulting problem structure can depend on the
chosen solver. If you do not have a Global Optimization Toolbox license, you must specify the solver. See Integer Constraints in Nonlinear ProblemBased Optimization.
The default solver for each optimization problem type is listed here.
Problem Type  Default Solver 

Linear Programming (LP)  linprog 
MixedInteger Linear Programming (MILP)  intlinprog 
Quadratic Programming (QP)  quadprog 
SecondOrder Cone Programming (SOCP)  coneprog 
Linear Least Squares  lsqlin 
Nonlinear Least Squares  lsqnonlin 
Nonlinear Programming (NLP)  
MixedInteger Nonlinear Programming (MINLP)  ga (Global Optimization Toolbox) 
Multiobjective  gamultiobj (Global Optimization Toolbox) 
In this table, means the solver is available for the problem type, x means the solver is not available.
Problem Type  LP  MILP  QP  SOCP  Linear Least Squares  Nonlinear Least Squares  NLP  MINLP 

Solver  
linprog 
 x  x  x  x  x  x  x 
intlinprog 

 x  x  x  x  x  x 
quadprog 
 x 


 x  x  x 
coneprog 
 x  x 
 x  x  x  x 
lsqlin  x  x  x  x 
 x  x  x 
lsqnonneg  x  x  x  x 
 x  x  x 
lsqnonlin  x  x  x  x 

 x  x 
fminunc 
 x 
 x 


 x 
fmincon 
 x 




 x 
patternsearch (Global Optimization Toolbox) 
 x 




 x 
ga (Global Optimization Toolbox) 








particleswarm (Global Optimization Toolbox) 
 x 
 x 


 x 
simulannealbnd (Global Optimization Toolbox) 
 x 
 x 


 x 
surrogateopt (Global Optimization Toolbox) 








gamultiobj (Global Optimization Toolbox) 








paretosearch (Global Optimization Toolbox) 
 x 




 x 
Note
If you choose lsqcurvefit
as the solver for a leastsquares
problem, solve
uses lsqnonlin
. The
lsqcurvefit
and lsqnonlin
solvers are
identical for solve
.
Caution
For maximization problems (prob.ObjectiveSense
is
"max"
or "maximize"
), do not specify a
leastsquares solver (one with a name beginning lsq
). If you do,
solve
throws an error, because these solvers cannot
maximize.
For equation solving, this table contains the available solvers for each problem type. In the table,
* indicates the default solver for the problem type.
Y indicates an available solver.
N indicates an unavailable solver.
Supported Solvers for Equations
Equation Type  lsqlin  lsqnonneg  fzero  fsolve  lsqnonlin 

Linear  *  N  Y (scalar only)  Y  Y 
Linear plus bounds  *  Y  N  N  Y 
Scalar nonlinear  N  N  *  Y  Y 
Nonlinear system  N  N  N  *  Y 
Nonlinear system plus bounds  N  N  N  N  * 
Example: 'intlinprog'
Data Types: char
 string
Output Arguments
problem
— Problem structure
fmincon
problem structure  fminunc
problem structure  fsolve
problem structure  intlinprog
problem structure  linprog
problem structure  lsqlin
problem structure  lsqnonlin
problem structure  quadprog
problem structure  ga
problem structure
Problem structure, returned as an fmincon
problem
structure,
fminunc
problem
structure,
fsolve
problem
structure,
intlinprog
problem
structure,
linprog
problem
structure,
lsqlin
problem
structure,
lsqnonlin
problem
structure,
quadprog
problem
structure, or
ga
problem
(Global Optimization Toolbox)
structure.
The following table gives the resulting default problem type for
optimization problems. You can also obtain nondefault problem types. For
example, for nonlinear boundconstrained problems, you can select most
Global Optimization Toolbox solvers by using the solver
argument.
Optimization Objective and Constraint Types (Linear Constraints Include Bounds)  Resulting Problem Type 

Linear objective and constraint functions. At least one problem variable has
the  intlinprog 
Linear objective and constraint functions. No problem variable has the
 linprog 
Linear constraint functions. The objective function is a constant plus a sum of squares of linear expressions.  lsqlin 
Bound constraints. The objective function is a constant plus a sum of squares of general nonlinear expressions.  lsqnonlin 
Linear constraint functions. General quadratic objective function.  quadprog 
General nonlinear objective function. No constraints.  fminunc 
General nonlinear objective function, and there is at least one constraint of any type. Or, there is at least one general nonlinear constraint function.  fmincon 
Nonlinear objective function or constraint function, and there is at least one integer variable.  ga 
The following table gives the resulting problem type for equation solving problems.
Equation Types  Resulting Problem Type 

Linear system with or without bounds  lsqlin 
Scalar (single) nonlinear equation  fzero 
Nonlinear system without constraints  fsolve 
Nonlinear system with bounds  lsqnonlin 
Note
For nonlinear problems, prob2struct
creates
function files for the objective and nonlinear constraint functions. For
objective and constraint functions that call supporting functions,
prob2struct
also creates supporting function
files and stores them in the FileLocation
folder.
To access extra parameters in generated functions, see Obtain Generated Function Details.
For linear and quadratic optimization problems, the problem structure
includes an additional field, f0
, that represents an
additive constant for the objective function. If you solve the problem
structure using the specified solver, the returned objective function value
does not include the f0
value. If you solve prob
using the solve
function, the returned objective function value
includes the f0
value.
If the ObjectiveSense of prob
is 'max'
or
'maximize'
, then problem
uses the
negative of the objective function in prob
because
solvers minimize. To maximize, they minimize the negative of the original
objective function. In this case, the reported optimal function value from
the solver is the negative of the value in the original problem. See Maximizing an Objective. You cannot use
lsqlin
for a maximization problem.
Tips
If you call
prob2struct
multiple times in the same MATLAB^{®} session for nonlinear problems, use theObjectiveFunctionName
orEquationFunctionName
argument and, if appropriate, theConstraintFunctionName
argument. Specifying unique names ensures that the resulting problem structures refer to the correct objective and constraint functions. Otherwise, subsequent calls toprob2struct
can cause the generated nonlinear function files to overwrite existing files.To avoid causing an infinite recursion, do not call
prob2struct
inside an objective or constraint function.When calling
prob2struct
in parallel for nonlinear problems, ensure that the resulting objective and constraint function files have unique names. Doing so avoids each pass of the loop writing to the same file or files.
Algorithms
Conversion to Solver Form
The basis for the problem structure is an implicit ordering of all problem
variables into a single vector. The order of the problem variables is the same as
the order of the Variables
property in prob
. See OptimizationProblem
. You can also find the order by using varindex
.
For example, suppose that the problem variables are in this order:
x
— a 3by2by4 arrayy
— a 3by2 array
In this case, the implicit variable order is the same as if the problem variable
is vars = [x(:);y(:)]
.
The first 24 elements of vars
are equivalent to
x(:)
, and the next six elements are equivalent to
y(:)
, for a total of 30 elements. The lower and upper bounds
correspond to this variable ordering, and each linear constraint matrix has 30
columns.
For problems with general nonlinear objective or constraint functions,
prob2struct
creates function files in the current folder or
in the folder specified by FileLocation
. The returned
problem
structure refers to these function files.
Automatic Differentiation
Automatic differentiation (AD) applies to the solve
and
prob2struct
functions under the following conditions:
The objective and constraint functions are supported, as described in Supported Operations for Optimization Variables and Expressions. They do not require use of the
fcn2optimexpr
function.The solver called by
solve
isfmincon
,fminunc
,fsolve
, orlsqnonlin
.For optimization problems, the
'ObjectiveDerivative'
and'ConstraintDerivative'
namevalue pair arguments forsolve
orprob2struct
are set to'auto'
(default),'autoforward'
, or'autoreverse'
.For equation problems, the
'EquationDerivative'
option is set to'auto'
(default),'autoforward'
, or'autoreverse'
.
When AD Applies  All Constraint Functions Supported  One or More Constraints Not Supported 

Objective Function Supported  AD used for objective and constraints  AD used for objective only 
Objective Function Not Supported  AD used for constraints only  AD not used 
When these conditions are not satisfied, solve
estimates gradients by
finite differences, and prob2struct
does not create gradients in its
generated function files.
Solvers choose the following type of AD by default:
For a general nonlinear objective function,
fmincon
defaults to reverse AD for the objective function.fmincon
defaults to reverse AD for the nonlinear constraint function when the number of nonlinear constraints is less than the number of variables. Otherwise,fmincon
defaults to forward AD for the nonlinear constraint function.For a general nonlinear objective function,
fminunc
defaults to reverse AD.For a leastsquares objective function,
fmincon
andfminunc
default to forward AD for the objective function. For the definition of a problembased leastsquares objective function, see Write Objective Function for ProblemBased Least Squares.lsqnonlin
defaults to forward AD when the number of elements in the objective vector is greater than or equal to the number of variables. Otherwise,lsqnonlin
defaults to reverse AD.fsolve
defaults to forward AD when the number of equations is greater than or equal to the number of variables. Otherwise,fsolve
defaults to reverse AD.
Note
To use automatic derivatives in a problem converted by prob2struct
, pass options specifying these derivatives.
options = optimoptions('fmincon','SpecifyObjectiveGradient',true,... 'SpecifyConstraintGradient',true); problem.options = options;
Currently, AD works only for first derivatives; it does not apply to second or higher
derivatives. So, for example, if you want to use an analytic Hessian to speed your
optimization, you cannot use solve
directly, and must instead use the
approach described in Supply Derivatives in ProblemBased Workflow.
Version History
Introduced in R2017bR2021a: Options
NameValue Has Been Removed
Errors starting in R2021a
The Options
namevalue pair has been removed. To modify
options, edit the resulting problem
structure. For
example,
problem.options = optimoptions('fmincon',... 'Display','iter','MaxFunctionEvaluations',5e4); % Or, to set just one option: problem.options.MaxFunctionEvaluations = 5e4;
The Options
namevalue pair was removed because it can cause
ambiguity in the presence of automatic differentiation.
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
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)