# 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.

example

````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.```

example

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

example

````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

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 = 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 ```

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

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 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;`

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')```

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 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;```

Example: `'finite-differences'`

Data Types: `char` | `string`

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`

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`

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 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;```

Example: `'finite-differences'`

Data Types: `char` | `string`

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

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, 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.

`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

collapse all

### 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:

When AD AppliesAll Constraint Functions SupportedOne or More Constraints Not Supported
Objective Function SupportedAD used for objective and constraintsAD used for objective only

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` and `fminunc` 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.

## Compatibility Considerations

expand all

Errors starting in R2021a