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

This property is read-only.

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

Data Types: struct

Object Functions

infeasibilityConstraint violation at a point
showDisplay optimization object
writeSave 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 i2.

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;

Introduced in R2019b