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 nodes 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 node's predecessors in the model.

iter_successors()

Iterate over a node's successors in the model.

maybe_equals(other)

Compare to another node.

reset_state(index)

Reset the state of a node and any successor symbols.

shares_memory(other)

Determine if two symbols share memory.

state_size()

Return an estimated size, in bytes, of the node's state.

topological_index()

Topological index of the node.

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.

has_state([index])

Return the initialization status of the indexed state.

max()

Create a Max symbol.

maybe_equals(other)

Compare to another node.

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()

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

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

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

Parameters:

other – Another node 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 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 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.