prob2struct - Convert optimization problem or equation problem to solver form - MATLAB (original) (raw)

Convert optimization problem or equation problem to solver form

Syntax

Description

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

[problem](#mw%5Fd550a523-5099-44f9-8457-187518647a55) = prob2struct([prob](#mw%5Fd7b92ea7-e659-4f72-9d20-254de293c04b%5Fsep%5Fmw%5F0c2aa71b-f426-4eb2-a081-bcfc19dc9d54)) 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.

example

[problem](#mw%5Fd550a523-5099-44f9-8457-187518647a55) = prob2struct([prob](#mw%5Fd7b92ea7-e659-4f72-9d20-254de293c04b%5Fsep%5Fmw%5F0c2aa71b-f426-4eb2-a081-bcfc19dc9d54),[x0](#mw%5Fd7b92ea7-e659-4f72-9d20-254de293c04b%5Fsep%5Fmw%5Fc1a24646-7c73-4b73-b0a0-a7af7c3d9101)) also converts the initial point structure x0 and includes it inproblem.

example

[problem](#mw%5Fd550a523-5099-44f9-8457-187518647a55) = prob2struct(___,[Name,Value](#namevaluepairarguments)), 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 thatprob2struct creates an objective function file namedobjfun1.m in the current folder.

example

Examples

collapse all

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 = costIngotsingots + 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 + carbonAlloysalloys; totalMolyb = (weightIngots.*molybIngots)ingots + molybAlloysalloys;

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 = 3×8 sparse double matrix (24 nonzeros) (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 = 3×1

25.0000 1.2500 1.2500

Examine the bounds.

ans = 8×1

 0
 0
 0
 0
 0
 0
 0
 0

ans = 8×1

Inf Inf Inf Inf 1 1 1 1

Solve the problem by calling intlinprog.

Running HiGHS 1.7.1: Copyright (c) 2024 HiGHS under MIT licence terms Coefficient ranges: Matrix [3e-02, 6e+00] Cost [1e+02, 2e+03] Bound [1e+00, 1e+00] RHS [1e+00, 2e+01] Presolving model 3 rows, 8 cols, 24 nonzeros 0s 3 rows, 8 cols, 18 nonzeros 0s

Solving MIP model with: 3 rows 8 cols (4 binary, 0 integer, 0 implied int., 4 continuous) 18 nonzeros

    Nodes      |    B&B Tree     |            Objective Bounds              |  Dynamic Constraints |       Work      
 Proc. InQueue |  Leaves   Expl. | BestBound       BestSol              Gap |   Cuts   InLp Confl. | LpIters     Time

     0       0         0   0.00%   0               inf                  inf        0      0      0         0     0.0s
     0       0         0   0.00%   8125.6          inf                  inf        0      0      0         4     0.0s

R 0 0 0 0.00% 8495 8495 0.00% 5 0 0 5 0.0s

Solving report Status Optimal Primal bound 8495 Dual bound 8495 Gap 0% (tolerance: 0.01%) Solution status feasible 8495 (objective) 0 (bound viol.) 0 (int. viol.) 0 (row viol.) Timing 0.02 (total) 0.01 (presolve) 0.00 (postsolve) Nodes 1 LP iterations 5 (total) 0 (strong br.) 1 (separation) 0 (heuristics)

Optimal solution found.

Intlinprog stopped at the root node because the objective value is within a gap tolerance of the optimal value, options.AbsoluteGapTolerance = 1e-06. The intcon variables are integer within tolerance, options.ConstraintTolerance = 1e-06.

x = 8×1

7.2500
     0
0.2500
3.5000
1.0000
1.0000
     0
1.0000

Create a nonlinear problem in the problem-based framework.

x = optimvar('x',2); fun = log(1 + 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 'logrosenbrock' and the constraint function file 'circle2'.

problem = prob2struct(prob,x0,'ObjectiveFunctionName','logrosenbrock',... '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.

Input Arguments

collapse all

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 the following: an objective function, nonlinear equalities, and nonlinear inequalities. If a function calculation has a complex value, even as an intermediate value, the final result might be incorrect.

Example: prob = optimproblem; prob.Objective = obj; prob.Constraints.cons1 = cons1;

Example: prob = eqnproblem; prob.Equations = eqs;

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) and particleswarm (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

Name-Value Arguments

collapse all

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value 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')

Indication to use automatic differentiation (AD) for nonlinear constraint functions, specified as the comma-separated pair consisting of 'ConstraintDerivative' and'auto' (use AD if possible),'auto-forward' (use forward AD if possible),'auto-reverse' (use reverse AD if possible), or'finite-differences' (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 inSupported Operations for 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;

Example: 'finite-differences'

Data Types: char | string

Name of the nonlinear constraint function file created byprob2struct for an optimization problem, specified as the comma-separated pair consisting of'ConstraintFunctionName' and a file name. This argument applies to fmincon orfminunc 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, thenprob2struct overwrites'generatedConstraints.m'. If you do not specifyFileLocation, thenprob2struct creates the file in the current folder.

The returned problem structure refers to this function file.

Example: "mynlcons"

Data Types: char | string

Name of the nonlinear equation function file created byprob2struct 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, thenprob2struct overwrites'generatedEquation.m'. If you do not specifyFileLocation, thenprob2struct creates the file in the current folder.

The returned problem structure refers to this function file.

Example: "myequation"

Data Types: char | string

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

Indication to use automatic differentiation (AD) for nonlinear objective function, specified as the comma-separated pair consisting of'ObjectiveDerivative' and'auto' (use AD if possible),'auto-forward' (use forward AD if possible),'auto-reverse' (use reverse AD if possible), or'finite-differences' (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 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;

Example: 'finite-differences'

Data Types: char | string

Name of the objective function file created byprob2struct for an optimization problem, specified as the comma-separated pair consisting of'ObjectiveFunctionName' and a file name. This argument applies to fmincon orfminunc 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, thenprob2struct overwrites'generatedObjective.m'. If you do not specifyFileLocation, thenprob2struct creates the file in the current folder.

The returned problem structure refers to this function file.

Example: "myobj"

Data Types: char | string

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 usingprob2struct, 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 Problem-Based Optimization.

The default solver for each optimization problem type is listed here.

In this table, means the solver is available for the problem type,x means the solver is not available.

Note

If you choose lsqcurvefit as the solver for a least-squares problem, solve uses lsqnonlin. Thelsqcurvefit and lsqnonlin solvers are identical for solve.

Caution

For maximization problems (prob.ObjectiveSense is"max" or "maximize"), do not specify a least-squares 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

Example: 'intlinprog'

Data Types: char | string

Output Arguments

collapse all

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, orga 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 bound-constrained problems, you can select mostGlobal Optimization Toolbox solvers by using the solver argument.

The following table gives the resulting problem type for equation solving problems.

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 uselsqlin for a maximization problem.

Tips

• If you call prob2struct multiple times in the same MATLAB® session for nonlinear problems, use theObjectiveFunctionName or EquationFunctionName 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 callprob2struct 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

collapse all

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 tox(:), and the next six elements are equivalent toy(:), 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 returnedproblem structure refers to these function files.

Automatic differentiation (AD) applies to the solve andprob2struct 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 is fmincon, fminunc, fsolve, or lsqnonlin.
• For optimization problems, the 'ObjectiveDerivative' and'ConstraintDerivative' name-value pair arguments forsolve or prob2struct are set to'auto' (default), 'auto-forward', or'auto-reverse'.
• For equation problems, the 'EquationDerivative' option is set to 'auto' (default), 'auto-forward', or'auto-reverse'.

Note

For linear or quadratic objective or constraint functions, applicable solvers always use explicit function gradients. These gradients are not produced using AD. See Closed Form.

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 least-squares objective function, fmincon andfminunc default to forward AD for the objective function. For the definition of a problem-based least-squares objective function, see Write Objective Function for Problem-Based 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 Problem-Based Workflow.

Version History

Introduced in R2017b

expand all

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