Documentation

# OptimizationEquality

Equalities and equality constraints

## Description

An `OptimizationEquality` object contains equalities and equality constraints in terms of `OptimizationVariable` objects or `OptimizationExpression` objects. Each equality uses the comparison operator `==`.

A single statement can represent an array of equalities. For example, you can express the equalities that each row of a matrix variable `x` sums to one in this single statement:

`constrsum = sum(x,2) == 1`

Use `OptimizationEquality` objects as constraints in an `OptimizationProblem`, or as equations in an `EquationProblem`.

## Creation

Create equalities using optimization expressions with the comparison operator `==`.

Include equalities in the `Constraints` property of an optimization problem, or the `Equations` property of an equation problem, by using dot notation.

```prob = optimproblem; x = optimvar(x,4,6); SumToOne = sum(x,2) == 1; prob.Constraints.SumToOne = SumToOne; % Or for an equation problem: eqprob = eqnproblem; eqprob.Equations.SumToOne = SumToOne;```

You can also create an empty optimization equality by using `optimeq` or `optimconstr`. Typically, you then set the equalities in a loop. For an example, see Create Equalities in Loop. However, for the most efficient problem formulation, avoid setting equalities in loops. See Create Efficient Optimization Problems.

## Properties

expand all

Index names, specified as a cell array of strings or character vectors. For information on using index names, see Named Index for Optimization Variables.

Data Types: `cell`

Optimization variables in the object, specified as a structure of `OptimizationVariable` objects.

Data Types: `struct`

## Object Functions

 `infeasibility` Constraint violation at a point `show` Display optimization object `write` Save optimization object description

## Examples

collapse all

Create a 4-by-6 optimization variable matrix named x.

`x = optimvar('x',4,6);`

Create the equalities that each row of x sums to one.

`constrsum = sum(x,2) == 1`
```constrsum = 4×1 Linear OptimizationEquality array with properties: IndexNames: {{} {}} Variables: [1×1 struct] containing 1 OptimizationVariable See equality formulation with show. ```

View the equalities.

`show(constrsum)`
```(1, 1) x(1, 1) + x(1, 2) + x(1, 3) + x(1, 4) + x(1, 5) + x(1, 6) == 1 (2, 1) x(2, 1) + x(2, 2) + x(2, 3) + x(2, 4) + x(2, 5) + x(2, 6) == 1 (3, 1) x(3, 1) + x(3, 2) + x(3, 3) + x(3, 4) + x(3, 5) + x(3, 6) == 1 (4, 1) x(4, 1) + x(4, 2) + x(4, 3) + x(4, 4) + x(4, 5) + x(4, 6) == 1 ```

To include the equalities in an optimization problem, set a `Constraints` property to `constrsum` by using dot notation.

```prob = optimproblem; prob.Constraints.constrsum = constrsum```
```prob = OptimizationProblem with properties: Description: '' ObjectiveSense: 'minimize' Variables: [1×1 struct] containing 1 OptimizationVariable Objective: [0×0 OptimizationExpression] Constraints: [1×1 struct] containing 1 OptimizationConstraint See problem formulation with show. ```

Similarly, to include the equalities in an equation problem, set a `Constraints` property to `constrsum` by using dot notation.

```eqnprob = eqnproblem; eqnprob.Equations.constrsum = constrsum```
```eqnprob = EquationProblem with properties: Description: '' Variables: [1×1 struct] containing 1 OptimizationVariable Equations: [1×1 struct] containing 1 OptimizationEquality See problem formulation with show. ```

Create an empty `OptimizationEquality` object.

`eq1 = optimeq;`

Create a 5-by-5 optimization variable array named `x`.

`x = optimvar('x',5,5);`

Create the equalities that row $i$ of `x` sums to ${i}^{2}$.

```for i = 1:size(x,1) eq1(i) = sum(x(i,:)) == i^2; end```

View the resulting equalities.

`show(eq1)`
```(1, 1) x(1, 1) + x(1, 2) + x(1, 3) + x(1, 4) + x(1, 5) == 1 (1, 2) x(2, 1) + x(2, 2) + x(2, 3) + x(2, 4) + x(2, 5) == 4 (1, 3) x(3, 1) + x(3, 2) + x(3, 3) + x(3, 4) + x(3, 5) == 9 (1, 4) x(4, 1) + x(4, 2) + x(4, 3) + x(4, 4) + x(4, 5) == 16 (1, 5) x(5, 1) + x(5, 2) + x(5, 3) + x(5, 4) + x(5, 5) == 25 ```

To use `eq1` as a constraint in an optimization problem, set `eq1` as a `Constraints` property by using dot notation.

```prob = optimproblem; prob.Constraints.eq1 = eq1;```

Similarly, to use `eq1` as a set of equations in an equation problem, set `eq1` as an `Equations` property by using dot notation.

```eqprob = eqnproblem; eqprob.Equations.eq1 = eq1;```