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.

Tip

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

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

IndexNames — Index names

'' (default) | cell array of strings | cell array of character vectors

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

Variables — Optimization variables in object

Read-only: structure of OptimizationVariable objects

This property is read-only.

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

Data Types: struct

Object Functions

evaluate	Evaluate optimization expression or objectives and constraints in problem
infeasibility	Constraint violation at a point
issatisfied	Constraint satisfaction of an optimization problem at a set of points
show	Display information about optimization object
write	Save optimization object description

Examples

Create OptimizationEquality Array

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 Equalities in Loop

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;

Check Constraints

Check the value of an inequality constraint and satisfaction of an equality constraint at a point specified by a structure.

x = optimvar("x");
y = optimvar("y");
ineq = x^2 + y^2/4 <= 2;
eq = 4*x^2 + y^2 == 5;
x0.x = 1;
x0.y = 1;
evaluate(ineq,x0) % Value = L - R, where L =  x^2 + y^2/4 and R = 2

ans = 
-0.7500

issatisfied(eq,x0) % Checks whether 4*x^2 + y^2 = 5

ans = logical
   1

Version History

Introduced in R2019b

R2024b: OptimizationEquality supports evaluate and issatisfied

You can now evaluate optimization expressions and constraints using evaluate and issatisfied for OptimizationEquality objects.

The value of a constraint depends on the constraint type. An equation is equivalent to an == constraint. For expressions L and R:

Constraint Type	Value
L <= R	L – R
L >= R	R – L
L == R	abs(L – R)

For details, see the evaluate and issatisfied reference pages.