Symbols#

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

See the Symbols section for an introduction to working with symbols.

All symbols listed in the Model Symbols subsection below inherit from the Symbol class and, for most mathematical symbols, the ArraySymbol class.

Symbol#

All symbols inherit from the Symbol class and therefore inherit its methods.

class Symbol[source]#

Base class for symbols.

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

equals(other)[source]#

Compare whether two symbols are identical.

Parameters:: other – A symbol for comparison.

Equal symbols represent the same quantity in the model.

Note that comparing symbols across models is expensive.

See also

Symbol.maybe_equals(): an alternative for equality testing that can return false positives but is faster.

has_state(index=0)[source]#

Return the initialization status of the indexed state.

Parameters:: index – Index of the queried state.
Returns:: True if the state is initialized.

id()[source]#

Return the “identity” of the underlying node.

This identity is unique to the underlying node, rather than the identity of the Python object representing it. Therefore, symdol.id() is not the same as id(symbol)!

Examples

>>> from dwave.optimization import Model
...
>>> model = Model()
>>> a = model.binary()
>>> aa, = model.iter_symbols()
>>> assert a.id() == aa.id()
>>> assert id(a) != id(aa)

While symbols are not hashable, the .id() is.

>>> model = Model()
>>> x = model.integer()
>>> seen = {x.id()}

See also

shares_memory(): a.shares_memory(b) is equivalent to a.id() == b.id().

equals(): a.equals(b) will return True if a.id() == b.id(). Though the inverse is not necessarily true.

iter_predecessors()[source]#

Iterate over a symbol’s predecessors in the model.

Examples

This example constructs a \(b = \sum a\) model, where \(a\) is a multiplication of two symbols, and iterates over the predecessor’s of \(b\) (which is just \(a\)).

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> i = model.integer((2, 2), upper_bound=20)
>>> c = model.constant([[21, 11], [10, 4]])
>>> a = c * i
>>> b = a.sum()
>>> a.equals(next(b.iter_predecessors()))
True

iter_successors()[source]#

Iterate over a symbol’s successors in the model.

Examples

This example constructs iterates over the successor symbols of a DisjointLists symbol.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> lsymbol, lsymbol_lists = model.disjoint_lists(
...     primary_set_size=5,
...     num_disjoint_lists=2)
>>> lsymbol_lists[0].equals(next(lsymbol.iter_successors()))
True

maybe_equals(other)[source]#

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.

reset_state(index)[source]#

Reset the state of a symbol and any successor symbols.

Parameters:: index – Index of the state to reset.

Examples

This example sets two states on a symbol with two successor symbols and resets just one state.

>>> from dwave.optimization import Model
>>> model = Model()
>>> lsymbol, lsymbol_lists = model.disjoint_lists(primary_set_size=5, num_disjoint_lists=2)
>>> with model.lock():
...     model.states.resize(2)
...     lsymbol.set_state(0, [[0, 4], [1, 2, 3]])
...     lsymbol.set_state(1, [[3, 4], [0, 1, 2]])
...     print(f"state 0: {lsymbol_lists[0].state(0)} and {lsymbol_lists[1].state(0)}")
...     print(f"state 1: {lsymbol_lists[0].state(1)} and {lsymbol_lists[1].state(1)}")
...     lsymbol.reset_state(0)
...     print("After reset:")
...     print(f"state 0: {lsymbol_lists[0].state(0)} and {lsymbol_lists[1].state(0)}")
...     print(f"state 1: {lsymbol_lists[0].state(1)} and {lsymbol_lists[1].state(1)}")
state 0: [0. 4.] and [1. 2. 3.]
state 1: [3. 4.] and [0. 1. 2.]
After reset:
state 0: [0. 1. 2. 3. 4.] and []
state 1: [3. 4.] and [0. 1. 2.]

shares_memory(other)[source]#

Determine if two symbols share memory.

Parameters:: other – Another symbol.
Returns:: True if the two symbols share memory.

state_size()[source]#

Return an estimated size, in bytes, of a symbol’s state.

The number of bytes returned by this method is only an estimate. Some symbols hold additional information that is not accounted for.

For most symbols, which are arrays, this method is subclassed by the state_size method.

See also

ArraySymbol.state_size() An estimate of the size of an array symbol’s state.

Model.state_size() An estimate of the size of a model’s state.

topological_index()[source]#

Topological index of the symbol.

Return None if the model is not topologically sorted.

Examples

This example prints the indices of a two-symbol model.

>>> from dwave.optimization import Model
>>> model = Model()
>>> i = model.integer(100, lower_bound=20)
>>> sum_i = i.sum()
>>> with model.lock():
...     for symbol in model.iter_symbols():
...         print(f"Symbol {type(symbol)} is node {symbol.topological_index()}")
Symbol <class 'dwave.optimization.symbols.IntegerVariable'> is node 0
Symbol <class 'dwave.optimization.symbols.Sum'> is node 1

ArraySymbol#

Most mathematical symbols inherit from the ArraySymbol class and therefore inherit its methods.

class ArraySymbol[source]#

Bases: Symbol

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

all()[source]#

Create an All symbol.

The new symbol returns True when all elements evaluate to True.

any()[source]#

Create an Any symbol.

The new symbol returns True when any elements evaluate to True.

Added in version 0.4.1.

copy()[source]#: Return an array symbol that is a copy of the array.

See also

Copy Equivalent class.

Added in version 0.5.1.

flatten()[source]#

Return an array symbol collapsed into one dimension.

Equivalent to symbol.reshape(-1).

max(*, initial=None)[source]#

Create a Max symbol.

The new symbol returns the maximum value in its elements.

Parameters:

initial –

The starting value for the product operation.

Added in version 0.6.4.

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_max = i.max()
>>> type(i_max)
<class 'dwave.optimization.symbols.Max'>

See also

Max

maybe_equals(other)[source]#

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.

min(*, initial=None)[source]#

Create a Min symbol.

The new symbol returns the minimum value in its elements.

Parameters:

initial –

The starting value for the product operation.

Added in version 0.6.4.

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'>

See also

Min

ndim()[source]#: Return the number of dimensions for a symbol.

prod(*, axis=None, initial=None)[source]#

Create a Prod symbol.

The new symbol returns the product of its elements.

Parameters:

axis –
Axis along which the a product operation is performed.

Added in version 0.5.1.
initial –
The starting value for the product operation.

Added in version 0.6.4.

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()  
<dwave.optimization.symbols.Prod at ...>

See also

PartialProd Prod

reshape(*shape)[source]#

Create a Reshape symbol.

Parameters:: shape – Shape of the created symbol.

The new symbol reshapes without changing the antecedent symbol’s data.

Examples

This example reshapes a column vector into a row vector.

>>> from dwave.optimization import Model
>>> model = Model()
>>> j = model.integer(3, lower_bound=-10, upper_bound=10)
>>> j.shape()
(3,)
>>> k = j.reshape((1, 3))
>>> k.shape()
(1, 3)

resize(shape, fill_value=None)[source]#

Return a new Resize symbol with the given shape.

Parameters:

shape – Shape of the new array. All dimension sizes must be non-negative.
fill_value – The value to be used if the resulting array is larger than the given one. Defaults to 0.

Returns:

A Resize symbol.

Examples

>>> from dwave.optimization import Model
...
>>> model = Model()
>>> s = model.set(10)  # subsets of range(10)
>>> s_2x2 = s.resize((2, 2), fill_value=-1)
...
>>> model.states.resize(1)
>>> with model.lock():
...     s.set_state(0, [0, 1, 2])
...     print(s_2x2.state(0))
[[ 0.  1.]
 [ 2. -1.]]

See also

resize(): equivalent function.

Resize: equivalent symbol.

Added in version 0.6.4.

shape()[source]#

Return the shape of the symbol.

A dynamic array symbol returns a -1 in the first dimension.

Examples

This example returns the shape of a newly instantiated symbol.

>>> from dwave.optimization import Model
>>> model = Model()
>>> x = model.binary(20)
>>> x.shape()
(20,)
>>> s = model.set(20)
>>> s.shape()
(-1,)

size()[source]#

Return the number of elements in the symbol.

If the symbol has a fixed size, returns that size as an integer. Otherwise, returns a Size symbol.

Examples

This example checks the size of a \(2 \times 3\) binary symbol.

>>> from dwave.optimization import Model
>>> model = Model()
>>> x = model.binary((2, 3))
>>> x.size()
6

state(index=0, *, copy=True)[source]#

Return the state of the symbol.

Parameters:

index – Index of the state.
copy – Currently only True is supported.

Returns:

State as a numpy.ndarray.

Examples

This example prints a symbol’s two states: initialized and uninitialized.

>>> from dwave.optimization import Model
>>> model = Model()
>>> x = model.binary((2, 3))
>>> z = x.sum()
>>> with model.lock():
...     model.states.resize(2)
...     x.set_state(0, [[0, 0, 1], [1, 0, 1]])
...     print(z.state(0))
...     print(z.state(1))
3.0
0.0

state_size()[source]#

Return an estimate of the size, in bytes, of an array symbol’s state.

For an array symbol, the estimate of the state size is exactly the number of bytes needed to encode the array.

Examples

This example returns the size of an integer symbol. In this example, the symbol encodes a \(5\times4\) of integers, each represented by a \(8\) byte float. Therefore the estimated state size is \(5*4*8 = 160\) bytes.

>>> from dwave.optimization import Model
>>> model = Model()
>>> i = model.integer((5, 4))  # 5x4 array of integers
>>> i.state_size()             # 5*4*8 bytes
160

See also

Symbol.state_size() An estimate of the size of a symbol’s state.

Model.state_size() An estimate of the size of a model’s state.

strides()[source]#

Return the stride length, in bytes, for traversing a symbol.

Returns:: Tuple of the number of bytes to step in each dimension when traversing a symbol.

Examples

This example returns the size of an integer symbol.

>>> from dwave.optimization import Model
>>> model = Model()
>>> i = model.integer((2, 3), upper_bound=20)
>>> i.strides()
(24, 8)

sum(*, axis=None, initial=None)[source]#

Create a Sum symbol.

The new symbol returns the sum of its elements.

Parameters:

axis –
Axis along which the a plus operation is performed.

Added in version 0.4.1.
initial –
The starting value for the plus operation.

Added in version 0.6.4.

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.sum()  
<dwave.optimization.symbols.Sum at ...>

See also

PartialSum Sum

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 ARange#