Symbols

Symbols are a model’s decision variables, intermediate variables, constants, and mathematical operations.

See Symbols for an introduction to working with symbols.

Base Classes

class Symbol

Base class for symbols.

Each symbol corresponds to a node in the directed acyclic graph representing the problem.

The following Symbol methods are inherited by the ArraySymbol class and model symbols.

equals(other)	Compare whether two symbols are identical.
has_state([index])	Return the initialization status of the indexed state.
id()	Return the "identity" of the underlying node.
iter_predecessors()	Iterate over a symbol's predecessors in the model.
iter_successors()	Iterate over a symbol's successors in the model.
maybe_equals(other)	Compare to another symbol.
reset_state(index)	Reset the state of a symbol and any successor symbols.
shares_memory(other)	Determine if two symbols share memory.
state_size()	Return an estimated size, in bytes, of the symbol's state.
topological_index()	Topological index of the symbol.

class ArraySymbol

Base class for symbols that can be interpreted as an array.

The following ArraySymbol methods are inherited by the model symbols.

all()	Create an All symbol.
any()	Create an Any symbol.
has_state([index])	Return the initialization status of the indexed state.
max()	Create a Max symbol.
maybe_equals(other)	Compare to another symbol.
min()	Create a Min symbol.
ndim()	Return the number of dimensions for a symbol.
prod()	Create a Prod symbol.
reshape(*shape)	Create a Reshape symbol.
sum([axis])	Create a Sum symbol.
shape()	Return the shape of the symbol.
size()	Return the number of elements in the symbol.
state([index, copy])	Return the state of the symbol.
state_size()	Return an estimated byte-size of the state.
strides()	Return the stride length, in bytes, for traversing a symbol.

Model Symbols

Each operation, decision, constant, mathematical function, and flow control is modeled using a symbol. The following symbols are available for modelling.

In general, symbols should be created using the methods inherited from Symbol and ArraySymbol, rather than by the constructors of the following classes.

class Absolute

Bases: ArraySymbol

Absolute value element-wise on a symbol.

Examples

This example adds the absolute value of an integer decision variable to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(1, lower_bound=-50, upper_bound=50)
>>> i_abs = abs(i)
>>> type(i_abs)
<class 'dwave.optimization.symbols.Absolute'>

class Add

Bases: ArraySymbol

Addition element-wise of two symbols.

Examples

This example adds two integer symbols.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(10, lower_bound=-50, upper_bound=50)
>>> j = model.integer(10, lower_bound=0, upper_bound=10)
>>> k = i + j
>>> type(k)
<class 'dwave.optimization.symbols.Add'>

class AdvancedIndexing

Bases: ArraySymbol

Advanced indexing.

Examples

This example uses advanced indexing to set a symbol’s values.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> prices = model.constant([i for i in range(20)])
>>> items = model.set(20)
>>> values = prices[items]
>>> type(values)
<class 'dwave.optimization.symbols.AdvancedIndexing'>

class All

Bases: ArraySymbol

Tests whether all elements evaluate to True.

Examples

This example checks all elements of a binary array.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> x = model.binary((20, 30))
>>> all_x = x.all()
>>> type(all_x)
<class 'dwave.optimization.symbols.All'>

class And

Bases: ArraySymbol

Boolean AND element-wise between two symbols.

See also

logical_and(): equivalent function.

class Any

Bases: ArraySymbol

Tests whether any elements evaluate to True.

Examples

This example checks the elements of a binary array.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> model.states.resize(1)
>>> x = model.constant([True, False, False])
>>> a = x.any()
>>> with model.lock():
...     assert a.state()

>>> y = model.constant([False, False, False])
>>> b = y.any()
>>> with model.lock():
...     assert not b.state()

Added in version 0.4.1.

class BasicIndexing

Bases: ArraySymbol

Basic indexing.

Examples

This example uses basic indexing to set a symbol’s values.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> prices = model.constant([i for i in range(20)])
>>> low_prices = prices[:10]
>>> type(low_prices)
<class 'dwave.optimization.symbols.BasicIndexing'>

class BinaryVariable

Bases: ArraySymbol

Binary decision-variable symbol.

Examples

This example adds a binary variable to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> x = model.binary((20, 30))
>>> type(x)
<class 'dwave.optimization.symbols.BinaryVariable'>

set_state(index, state)

Set the state of the binary symbol.

The given state must be binary array with the same shape as the symbol.

Parameters:

• index – Index of the state to set

• state – Assignment of values for the state.

Examples

This example sets two states for a \(2 \times 3\)-sized binary symbol.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> x = model.binary((2, 3))
>>> model.states.resize(2)
>>> x.set_state(0, [[True, True, False], [False, True, False]])
>>> x.set_state(1, [[False, True, False], [False, True, False]])

class Constant

Bases: ArraySymbol

Constant symbol.

Examples

This example adds a constant symbol to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> a = model.constant(20)
>>> type(a)
<class 'dwave.optimization.symbols.Constant'>

maybe_equals(other)

Compare to another symbol.

This method exists because a complete equality test can be expensive.

Parameters:

other – Another symbol in the model’s directed acyclic graph.

Returns: integer

Supported return values are:

• 0—Not equal (with certainty)

• 1—Might be equal (no guarantees); a complete equality test is necessary

• 2—Are equal (with certainty)

Examples

This example compares IntegerVariable symbols of different sizes.

>>> from dwave.optimization import Model
>>> model = Model()
>>> i = model.integer(3, lower_bound=0, upper_bound=20)
>>> j = model.integer(3, lower_bound=-10, upper_bound=10)
>>> k = model.integer(5, upper_bound=55)
>>> i.maybe_equals(j)
1
>>> i.maybe_equals(k)
0

See also

equals(): a more expensive form of equality testing.

state(index=0, *, copy=True)

Return the state of the constant symbol.

Parameters:

• index – Index of the state.

• copy – Copy the state. Currently only True is supported.

Returns:

A copy of the state.

class DisjointBitSet

Bases: ArraySymbol

Disjoint-sets successor symbol.

Examples

This example adds a disjoint-sets symbol to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> s = model.disjoint_bit_sets(primary_set_size=100, num_disjoint_sets=5)
>>> type(s[1][0])
<class 'dwave.optimization.symbols.DisjointBitSet'>

set_index()

Return the index for the set.

class DisjointBitSets

Bases: Symbol

Disjoint-sets decision-variable symbol.

Examples

This example adds a disjoint-sets symbol to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> s = model.disjoint_bit_sets(primary_set_size=100, num_disjoint_sets=5)
>>> type(s[0])
<class 'dwave.optimization.symbols.DisjointBitSets'>

num_disjoint_sets()

Return the number of disjoint sets in the symbol.

set_state(index, state)

Set the state of the disjoint-sets symbol.

The given state must be a partition of range(primary_set_size) into num_disjoint_sets() partitions, encoded as a 2D num_disjoint_sets \(\times\) primary_set_size Boolean array.

Parameters:

• index – Index of the state to set

• state – Assignment of values for the state.

class DisjointList

Bases: ArraySymbol

Disjoint-lists successor symbol.

Examples

This example adds a disjoint-lists symbol to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> l = model.disjoint_lists(primary_set_size=10, num_disjoint_lists=2)
>>> type(l[1][0])
<class 'dwave.optimization.symbols.DisjointList'>

list_index()

Return the index for the list.

class DisjointLists

Bases: Symbol

Disjoint-lists decision-variable symbol.

Examples

This example adds a disjoint-lists symbol to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> l = model.disjoint_lists(primary_set_size=10, num_disjoint_lists=2)
>>> type(l[0])
<class 'dwave.optimization.symbols.DisjointLists'>

num_disjoint_lists()

Return the number of disjoint lists in the symbol.

set_state(index, state)

Set the state of the disjoint-lists symbol.

The given state must be a partition of range(primary_set_size) into num_disjoint_lists() partitions as a list of lists.

Parameters:

• index – Index of the state to set

• state – Assignment of values for the state.

class Equal

Bases: ArraySymbol

Equality comparison element-wise between two symbols.

Examples

This example creates an equality operation between integer symbols.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(25, upper_bound=100)
>>> j = model.integer(25, lower_bound=-100)
>>> k = i == j
>>> type(k)
<class 'dwave.optimization.symbols.Equal'>

class IntegerVariable

Bases: ArraySymbol

Integer decision-variable symbol.

Examples

This example adds an integer symbol to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(25, upper_bound=100)
>>> type(i)
<class 'dwave.optimization.symbols.IntegerVariable'>

lower_bound()

The lowest value allowed for the integer symbol.

set_state(index, state)

Set the state of the integer node.

The given state must be integer array of the integer node shape.

upper_bound()

The highest value allowed for the integer symbol.

class LessEqual

Bases: ArraySymbol

Smaller-or-equal comparison element-wise between two symbols.

Examples

This example creates an inequality operation between integer symbols.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(25, upper_bound=100)
>>> j = model.integer(25, lower_bound=-100)
>>> k = i <= j
>>> type(k)
<class 'dwave.optimization.symbols.LessEqual'>

class ListVariable

Bases: ArraySymbol

List decision-variable symbol.

Examples

This example adds a list symbol to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> l = model.list(10)
>>> type(l)
<class 'dwave.optimization.symbols.ListVariable'>

set_state(index, state)

Set the state of the list node.

The given state must be a permuation of range(len(state)).

class Logical

Bases: ArraySymbol

Logical truth value element-wise on a symbol.

See also

logical(): equivalent function.

class Max

Bases: ArraySymbol

Maximum value in the elements of a symbol.

Examples

This example adds the maximum value of an integer decision variable to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(100, lower_bound=-50, upper_bound=50)
>>> i_max = i.max()
>>> type(i_max)
<class 'dwave.optimization.symbols.Max'>

class Maximum

Bases: ArraySymbol

Maximum values in an element-wise comparison of two symbols.

Examples

This example sets a symbol’s values to the maximum values of two integer decision variables.

>>> from dwave.optimization.model import Model
>>> from dwave.optimization.mathematical import maximum
...
>>> model = Model()
>>> i = model.integer(100, lower_bound=-50, upper_bound=50)
>>> j = model.integer(100, lower_bound=-20, upper_bound=150)
>>> k = maximum(i, j)
>>> type(k)
<class 'dwave.optimization.symbols.Maximum'>

class Min

Bases: ArraySymbol

Minimum value in the elements of a symbol.

Examples

This example adds the minimum value of an integer decision variable to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(100, lower_bound=-50, upper_bound=50)
>>> i_min = i.min()
>>> type(i_min)
<class 'dwave.optimization.symbols.Min'>

class Minimum

Bases: ArraySymbol

Minimum values in an element-wise comparison of two symbols.

Examples

This example sets a symbol’s values to the minimum values of two integer decision variables.

>>> from dwave.optimization.model import Model
>>> from dwave.optimization.mathematical import minimum
...
>>> model = Model()
>>> i = model.integer(100, lower_bound=-50, upper_bound=50)
>>> j = model.integer(100, lower_bound=-20, upper_bound=150)
>>> k = minimum(i, j)
>>> type(k)
<class 'dwave.optimization.symbols.Minimum'>

class Modulus

Bases: ArraySymbol

Modulus element-wise between two symbols.

Examples

This example calculates the modulus of two integer symbols.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(10, lower_bound=-50, upper_bound=50)
>>> j = model.integer(10, lower_bound=-20, upper_bound=150)
>>> k = i % j
>>> type(k)
<class 'dwave.optimization.symbols.Modulus'>

class Multiply

Bases: ArraySymbol

Multiplication element-wise between two symbols.

Examples

This example multiplies two integer symbols.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(10, lower_bound=-50, upper_bound=50)
>>> j = model.integer(10, lower_bound=0, upper_bound=10)
>>> k = i*j
>>> type(k)
<class 'dwave.optimization.symbols.Multiply'>

class NaryAdd

Bases: ArraySymbol

Addition element-wise of N symbols.

Examples

This example add three integer symbols.

>>> from dwave.optimization.model import Model
>>> from dwave.optimization.mathematical import add
...
>>> model = Model()
>>> i = model.integer((10, 10), lower_bound=-50, upper_bound=50)
>>> j = model.integer((10, 10), lower_bound=-20, upper_bound=150)
>>> k = model.integer((10, 10), lower_bound=0, upper_bound=100)
>>> l = add(i, j, k)
>>> type(l)
<class 'dwave.optimization.symbols.NaryAdd'>

class NaryMaximum

Bases: ArraySymbol

Maximum values in an element-wise comparison of N symbols.

Examples

This example sets a symbol’s values to the maximum values of three integer decision variables.

>>> from dwave.optimization.model import Model
>>> from dwave.optimization.mathematical import maximum
...
>>> model = Model()
>>> i = model.integer((10, 10), lower_bound=-50, upper_bound=50)
>>> j = model.integer((10, 10), lower_bound=-20, upper_bound=150)
>>> k = model.integer((10, 10), lower_bound=0, upper_bound=100)
>>> l = maximum(i, j, k)
>>> type(l)
<class 'dwave.optimization.symbols.NaryMaximum'>

class NaryMinimum

Bases: ArraySymbol

Minimum values in an element-wise comparison of N symbols.

Examples

This example sets a symbol’s values to the minimum values of three integer decision variables.

>>> from dwave.optimization.model import Model
>>> from dwave.optimization.mathematical import minimum
...
>>> model = Model()
>>> i = model.integer((10, 10), lower_bound=-50, upper_bound=50)
>>> j = model.integer((10, 10), lower_bound=-20, upper_bound=150)
>>> k = model.integer((10, 10), lower_bound=0, upper_bound=100)
>>> l = minimum(i, j, k)
>>> type(l)
<class 'dwave.optimization.symbols.NaryMinimum'>

class NaryMultiply

Bases: ArraySymbol

Multiplication element-wise between N symbols.

Examples

This example multiplies three integer decision variables.

>>> from dwave.optimization.model import Model
>>> from dwave.optimization.mathematical import multiply
...
>>> model = Model()
>>> i = model.integer((10, 10), lower_bound=-50, upper_bound=50)
>>> j = model.integer((10, 10), lower_bound=-20, upper_bound=150)
>>> k = model.integer((10, 10), lower_bound=0, upper_bound=100)
>>> l = multiply(i, j, k)
>>> type(l)
<class 'dwave.optimization.symbols.NaryMultiply'>

class Negative

Bases: ArraySymbol

Numerical negative element-wise on a symbol.

Examples

This example add the negative of an integer array.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(100, upper_bound=50)
>>> i_minus = -i
>>> type(i_minus)
<class 'dwave.optimization.symbols.Negative'>

class Not

Bases: ArraySymbol

Logical negation element-wise on a symbol.

See also

logical_not(): equivalent function.

class Or

Bases: ArraySymbol

Boolean OR element-wise between two symbols.

See also

logical_or(): equivalent function.

class PartialSum

Bases: ArraySymbol

Sum of the elements of a symbol along an axis.

Examples

This example adds the sum of a binary symbol along an axis to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> x = model.binary((10, 5))
>>> x_sum_0 = x.sum(axis=0)
>>> type(x_sum_0)
<class 'dwave.optimization.symbols.PartialSum'>

class Permutation

Bases: ArraySymbol

Permutation of the elements of a symbol.

Examples

This example creates a permutation of a constant symbol.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> C = model.constant([[1, 2, 3], [2, 3, 1], [0, 1, 0]])
>>> l = model.list(3)
>>> p = C[l, :][:, l]
>>> type(p)
<class 'dwave.optimization.symbols.Permutation'>

class Prod

Bases: ArraySymbol

Product of the elements of a symbol.

Examples

This example adds the product of an integer symbol’s elements to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(100, lower_bound=-50, upper_bound=50)
>>> i_prod = i.prod()
>>> type(i_prod)
<class 'dwave.optimization.symbols.Prod'>

class QuadraticModel

Bases: ArraySymbol

Quadratic model.

Examples

This example adds a quadratic model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> x = model.binary(3)
>>> Q = {(0, 0): 0, (0, 1): 1, (0, 2): 2, (1, 1): 1, (1, 2): 3, (2, 2): 2}
>>> qm = model.quadratic_model(x, Q)
>>> type(qm)
<class 'dwave.optimization.symbols.QuadraticModel'>

get_linear(v)

Get the linear bias of v

get_quadratic(u, v)

Get the quadratic bias of u and v. Returns 0 if not present.

num_interactions()

The number of quadratic interactions in the quadratic model

num_variables()

The number of variables in the quadratic model.

class Reshape

Bases: ArraySymbol

Reshaped symbol.

Examples

This example adds a reshaped binary symbol.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> x = model.binary((2, 3))
>>> x_t = x.reshape((3, 2))
>>> type(x_t)
<class 'dwave.optimization.symbols.Reshape'>

class SetVariable

Bases: ArraySymbol

Set decision-variable symbol.

A set variable’s possible states are the subsets of range(n).

Parameters:

• model – The model.

• n – The possible states of the set variable are the subsets of range(n).

• min_size – The minimum set size.

• max_size – The maximum set size.

Examples

This example adds a set symbol to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> s = model.set(10)
>>> type(s)
<class 'dwave.optimization.symbols.SetVariable'>

set_state(index, state)

Set the state of the set node.

The given state must be a permuation of range(len(state)).

class Size

Bases: ArraySymbol

class Square

Bases: ArraySymbol

Squares element-wise of a symbol.

Examples

This example adds the squares of an integer decision variable to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(10, lower_bound=-5, upper_bound=5)
>>> ii = i**2
>>> type(ii)
<class 'dwave.optimization.symbols.Square'>

class Subtract

Bases: ArraySymbol

Subtraction element-wise of two symbols.

Examples

This example subtracts two integer symbols.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(10, lower_bound=-50, upper_bound=50)
>>> j = model.integer(10, lower_bound=0, upper_bound=10)
>>> k = i - j
>>> type(k)
<class 'dwave.optimization.symbols.Subtract'>

class Sum

Bases: ArraySymbol

Sum of the elements of a symbol.

Examples

This example adds the sum of an integer symbol’s elements to a model.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer(100, lower_bound=-50, upper_bound=50)
>>> i_sum = i.sum()
>>> type(i_sum)
<class 'dwave.optimization.symbols.Sum'>

class Where

Bases: ArraySymbol

Return elements chosen from x or y depending on condition.

See also

where(): equivalent function.

class Xor

Bases: ArraySymbol

Boolean XOR element-wise between two symbols.

See also

logical_xor(): equivalent function.

Added in version 0.4.1.