prob2struct

Convert optimization problem or equation problem to solver form

Syntax

problem = prob2struct(prob)

problem = prob2struct(prob,x0)

problem = prob2struct(___,Name,Value)

Description

Use prob2struct to convert an optimization problem or equation problem to solver form.

Tip

For the full workflow, see Problem-Based Optimization Workflow or Problem-Based Workflow for Solving Equations.

problem = prob2struct(prob) returns an optimization problem structure suitable for a solver-based solution. For nonlinear problems, prob2struct creates files for the objective function, and, if necessary, for nonlinear constraint functions and supporting files.

problem = prob2struct(prob,x0) also converts the initial point structure x0 and includes it in problem.

problem = prob2struct(___,Name,Value), for any input arguments, specifies additional options using one or more name-value pair arguments. For example, for a nonlinear optimization problem, 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 Mixed-Integer Linear Programming Basics: Problem-Based.

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 = 1e-05 (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 problem-based 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' name-value pair.

Solve the problem.

[x,fval] = fmincon(problem)

Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing 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.6187e-11

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 problem-based 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

Initial point, specified as a structure with field names equal to the variable names in prob.

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

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: problem = prob2struct(prob,'FileLocation','C:\Documents\myproblem')

'ConstraintDerivative' — Indication to use automatic differentiation for constraint functions

'auto' (default) | 'finite-differences'

Indication to use automatic differentiation (AD) for nonlinear constraint functions, specified as the comma-separated pair consisting of 'ConstraintDerivative' and either 'auto' (use AD if possible) or 'finite-differences' (do not use AD). 'auto' causes the resulting constraint function file to include derivative information provided that the constraint functions are supported, as described in Supported Operations on Optimization Variables and Expressions. For an example, see Supply Derivatives in Problem-Based 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;

Warning

The 'ObjectiveDerivative' and 'ConstraintDerivative' name-value pair arguments currently apply only to problems solved by fmincon or fminunc. If you attempt to use these arguments when solving an equation with solve or converting an equation with prob2struct, MATLAB^® issues an error.

Example: 'finite-differences'

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 comma-separated 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 comma-separated 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 comma-separated 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) | 'finite-differences'

Indication to use automatic differentiation (AD) for a nonlinear objective function, specified as the comma-separated pair consisting of 'ObjectiveDerivative' and either 'auto' (use AD if possible) or 'finite-differences' (do not use AD). 'auto' causes the resulting objective function file to include derivative information provided that the objective function is supported, as described in Supported Operations on Optimization Variables and Expressions. For an example, see Supply Derivatives in Problem-Based 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;

Warning

The 'ObjectiveDerivative' and 'ConstraintDerivative' name-value pair arguments currently apply only to problems solved by fmincon or fminunc. If you attempt to use these arguments when solving an equation with solve or converting an equation with prob2struct, MATLAB issues an error.

Example: 'finite-differences'

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 comma-separated 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

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

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, or quadprog problem structure.

The following table gives the resulting problem type for optimization problems.

Optimization Objective and Constraint Types (Linear Constraints Include Bounds)	Resulting Problem Type
Linear objective and constraint functions. At least one problem variable has the 'integer' type.	intlinprog
Linear objective and constraint functions. No problem variable has the 'integer' type.	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

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 the ObjectiveFunctionName or EquationFunctionName argument and, if appropriate, the ConstraintFunctionName argument. Specifying unique names ensures that the resulting problem structures refer to the correct objective and constraint functions. Otherwise, subsequent calls to prob2struct 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 3-by-2-by-4 array

• y — a 3-by-2 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 on Optimization Variables and Expressions. They do not require use of the fcn2optimexpr function.

• The solver called by solve is either fmincon or fminunc.

• The 'ObjectiveDerivative' and 'ConstraintDerivative' name-value pair arguments for solve or prob2struct are set to their default value, 'auto'.

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.

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 Problem-Based Workflow.

Compatibility Considerations

Options Name-Value Pair Will Be Removed

Not recommended starting in R2020b

The Options name-value pair will be removed in a future release. 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 name-value pair will be removed because it can cause ambiguity in the presence of automatic differentiation.