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

Base class for symbols.

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

equals(other)

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)

Return the initialization status of the indexed state.

Parameters:

index – Index of the queried state.

Returns:

True if the state is initialized.

id()

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

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

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()
>>> x = model.binary()
>>> y = x + 5
>>> y.equals(next(x.iter_successors()))
True

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.

reset_state(index)

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 = model.disjoint_lists_symbol(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[0].state(0)} and {lsymbol[1].state(0)}")
...     print(f"state 1: {lsymbol[0].state(1)} and {lsymbol[1].state(1)}")
...     lsymbol.reset_state(0)
...     print("After reset:")
...     print(f"state 0: {lsymbol[0].state(0)} and {lsymbol[1].state(0)}")
...     print(f"state 1: {lsymbol[0].state(1)} and {lsymbol[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)

Determine if two symbols share memory.

Parameters:

other – Another symbol.

Returns:

True if the two symbols share memory.

state_size()

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

Topological index of the symbol.

Return None if the model is not topologically sorted.

ArraySymbol

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

class ArraySymbol

Bases: Symbol

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

all(*, axis=None, initial=<no value>)

Create an All symbol.

Test whether all of the elements in the array evaluate to True.

Parameters:

• axis (int or tuple[int, ...], optional) –

  Axis or axes along which the operation is performed. If None, the reduction is performed over all dimensions. If tuple[int, ...], the reduction is performed along the specified axes.

  Added in version 0.6.8.

• initial (float or None, optional) –

  The starting value for the reduction. If None is given, the first element of the reduction is used.

  Added in version 0.6.8.

See also

All equivalent class.

any(*, axis=None, initial=False)

Create an Any symbol.

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

Parameters:

• axis (int or tuple[int, ...], optional) –

  Axis or axes along which the operation is performed. If None, the reduction is performed over all dimensions. If tuple[int, ...], the reduction is performed along the specified axes.

  Added in version 0.6.8.

• initial (float or None, optional) –

  The starting value for the reduction. If None is given, the first element of the reduction is used.

  Added in version 0.6.8.

See also

Any equivalent class.

Added in version 0.4.1.

copy()

Return an array symbol that is a copy of the array.

See also

Copy Equivalent class.

Added in version 0.5.1.

flatten()

Return an array symbol collapsed into one dimension.

Equivalent to symbol.reshape(-1).

info()

Information about the values and size of the array symbol.

Symbols sometimes need to know information about their predecessor(s) in order to determine whether they define a valid operation. For example, a Divide symbol does not permit its denominator to be 0.

This method returns a dataclass() with the following fields

• min: A lower bound (inclusive) on the values of the array.

• max: An upper bound (inclusive) on the values of the array.

• integral: Whether or not the values in the array will always be integral.

• size: The size of the array. If the array has a fixed size it will be an int. If the array has a dynamic size, this will instead be another dataclass() with the following fields

  • multiplier, symbol, and offset: The size of the array will be multiplier * (size of symbol) + offset. If the size of the array symbol is not a linear function of another symbol, the symbol field will just the self.

  • min: A lower bound (inclusive) on the size of the array. Will be None is the bound is not known.

  • max: An upper bound (inclusive) on the size of the array. Will be None is the bound is not known.

Examples

A constant symbol will have min, max, integral, and size determined by the array.

>>> import numpy as np
>>> from dwave.optimization import Model
...
>>> model = Model()
>>> c = model.constant(np.linspace(0, 4.5, num=10))
>>> c.info()
ArrayInfo(min=0.0, max=4.5, integral=False, size=10)

A set symbol is dynamic so its size cannot be expressed as an integer. However, its size is not derived from another symbol so its size is derived from itself.

>>> s = model.set(10)
>>> s.info()  
ArrayInfo(min=0.0, max=9.0, integral=True, size=...)
>>> sizeinfo = s.info().size  
>>> sizeinfo.multiplier
Fraction(1, 1)
>>> sizeinfo.symbol.id() == s.id()
True
>>> sizeinfo.offset
Fraction(0, 1)
>>> sizeinfo.min
0
>>> sizeinfo.max
10

When we index the constant array from the set we create another dynamic array with its size derived from set

>>> b = c[s]
>>> b.info()  
ArrayInfo(min=0.0, max=4.5, integral=False, size=...)
>>> sizeinfo = b.info().size  
>>> sizeinfo.multiplier
Fraction(1, 1)
>>> sizeinfo.symbol.id() == s.id()  # size is defined by the set
True
>>> sizeinfo.offset
Fraction(0, 1)
>>> sizeinfo.min
0
>>> sizeinfo.max
10

Added in version 0.6.8.

max(*, axis=None, initial=<no value>)

Create a Max symbol.

The new symbol returns the maximum value in its elements.

Parameters:

• axis (int or tuple[int, ...], optional) –

  Axis or axes along which the operation is performed. If None, the reduction is performed over all dimensions. If tuple[int, ...], the reduction is performed along the specified axes.

  Added in version 0.6.8.

• initial (float or None, optional) –

  The starting value for the reduction. If None is given, the first element of the reduction is used.

  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)

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(*, axis=None, initial=<no value>)

Create a Min symbol.

The new symbol returns the minimum value in its elements.

Parameters:

• axis (int or tuple[int, ...], optional) –

  Axis or axes along which the operation is performed. If None, the reduction is performed over all dimensions. If tuple[int, ...], the reduction is performed along the specified axes.

  Added in version 0.6.8.

• initial (float or None, optional) –

  The starting value for the reduction. If None is given, the first element of the reduction is used.

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

Return the number of dimensions for a symbol.

prod(*, axis=None, initial=<no value>)

Create a Prod symbol.

The new symbol returns the product of its elements.

Parameters:

• axis (int or tuple[int, ...], optional) –

  Axis or axes along which the operation is performed. If None, the reduction is performed over all dimensions. If tuple[int, ...], the reduction is performed along the specified axes.

  Added in version 0.5.1.

• initial (float or None, optional) –

  The starting value for the reduction. If None is given, the first element of the reduction is used.

  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

Prod equivalent symbol.

reshape(*shape)

Create a Reshape symbol.

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

Parameters:

shape – Shape of the created symbol. May be specified either as a single argument defining the shape or as the elements of the shape passed in as separate arguments. E.g., a.reshape((1, 2)) is equivalent to a.reshape(1, 2). One dimension can be -1, in which case it’s size is inferred from the other dimensions. For dynamically sized array symbols, the first dimension must be specified as -1 and the size of each “row” of the new array symbol cannot be a fraction of the size of each “row” of the antecedent array symbol. See examples below.

Returns:

A Reshape symbol, except when the provided shape exactly matches the shape of the symbol. In that case the symbol is returned.

Examples

This example reshapes a 1D vector into a 3x1 matrix.

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

This example reshapes a dynamic 2d array symbol.

>>> import numpy as np
...
>>> model = Model()
>>> a = model.constant(np.ones((10, 4)))[model.set(10), :]
>>> a.shape()
(-1, 4)
>>> b = a.reshape(-1, 2, 2)  # OK because 2*2 = 4
>>> b.shape()
(-1, 2, 2)
>>> c = a.reshape(-1, 4, 1, 1)  # OK because 4*1*1 = 4
>>> c.shape()
(-1, 4, 1, 1)
>>> d = a.reshape(-1, 2)  # OK because 2 evenly divides 4
>>> d.shape()
(-1, 2)
>>> a.reshape(-1, 8)  # Fails because 8 does not evenly divide 4 
Traceback (most recent call last):
ValueError: cannot reshape array of shape (-1, 4) into shape (-1, 8)

See also

Reshape: equivalent symbol.

Added in version 0.5.1.

Added in version 0.6.5: Add support for reshaping dynamic array symbols.

resize(shape, fill_value=None)

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

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

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)

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

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

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=<no value>)

Create a Sum symbol.

The new symbol returns the sum of its elements.

Parameters:

• axis (int or tuple[int, ...], optional) –

  Axis or axes along which the operation is performed. If None, the reduction is performed over all dimensions. If tuple[int, ...], the reduction is performed along the specified axes.

  Added in version 0.4.1.

• initial (float or None, optional) –

  The starting value for the reduction. If None is given, the first element of the reduction is used.

  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

Sum equivalent 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 ARange

Bases: ArraySymbol

Return evenly spaced integer values within a given interval.

See also

arange(): equivalent function.

Added in version 0.5.2.

class Absolute(x)

Bases: _UnaryOpSymbol

Absolute value element-wise on a symbol.

See also

absolute(): equivalent function.

class AccumulateZip

Bases: ArraySymbol

Using a supplied Expression, perform an element-wise accumulate operation along one or more array operands. The accumulate operation (represented by the Expression) takes as input one value from each of the operand arrays, as well as the result of the previously computed operation, and computes a new value at the next output index.

This takes inspiration from numpy.ufunc.accumulate but is different in that the accumulate operation can take an arbitrary number of arguments, instead of always two. These arguments come from “zipping” the supplied predecessor arrays together.

Thus if we are given an expression expr, predecessor arrays A, B, C, and an initial value init, this node is equivalent to the pseudocode:

r = [0] * len(A)
t = init
for args in zip(A, B, C):
    t = expr(t, *args)
    r[i] = t
return r

Parameters:

• expression – An Expression representing the accumulate operation. The first input on the expression will be given the previous output of the operation at each iteration over the values of the operands.

• operands – A list of the 1d-array symbols that will be the operands to the accumulate. There should be one fewer operands than inputs on the expression.

• initial (optional) – A float representing the value used to start the accumulate. This will be used to set the last input of the expression on the very first iteration.

Added in version 0.6.4.

class Add(lhs, rhs)

Bases: _BinaryOpSymbol

Addition element-wise of two symbols.

class AdvancedIndexing

Bases: ArraySymbol

Advanced indexing.

class All(array, *, axis=None, initial=<no value>)

Bases: _ReduceSymbol

Tests whether all elements evaluate to True.

See also

all() equivalent method.

class And(lhs, rhs)

Bases: _BinaryOpSymbol

Boolean AND element-wise between two symbols.

See also

logical_and(): equivalent function.

class Any(array, *, axis=None, initial=<no value>)

Bases: _ReduceSymbol

Tests whether any elements evaluate to True.

See also

any() equivalent method.

class ArgSort

Bases: ArraySymbol

Return an ordering of the indices that would sort (flattened) values of the given symbol. Note that while it will return an array with identical shape to the given symbol, the returned indices will always be indices on flattened array, similar to numpy.argsort(a, axis=None).

Always performs a index-wise stable sort such that the relative order of values is maintained in the returned order.

See also

argsort(): equivalent function.

Added in version 0.6.4.

class BSpline

Bases: ArraySymbol

Bspline node that takes in an array pointer, an integer degree and two vectors for knots and coefficients.

See also

bspline() equivalent function.

class BasicIndexing

Bases: ArraySymbol

Basic indexing.

class BinaryVariable

Bases: ArraySymbol

Binary decision-variable symbol.

See also

binary(): equivalent method.

lower_bound()

Lower bound(s) of Binary symbol.

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.

Examples

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

>>> from dwave.optimization.model import Model
>>> import numpy as np
...
>>> model = Model()
>>> x = model.binary((2, 3))
>>> model.states.resize(2)
>>> x.set_state(0, [[True, True, False], [False, True, False]])
>>> print(np.equal(x.state(0), [[True, True, False], [False, True, False]]).all())
True
>>> x.set_state(1, [[False, True, False], [False, True, False]])
>>> print(np.equal(x.state(1), [[False, True, False], [False, True, False]]).all())
True

upper_bound()

Upper bound(s) of Binary symbol.

class BroadcastTo

Bases: ArraySymbol

BroadcastTo symbol.

See also

broadcast_to(): equivalent function.

Added in version 0.6.5.

state_size()

Broadcasting symbols are stateless

class Concatenate

Bases: ArraySymbol

Concatenate symbol.

See also

concatenate() equivalent function.

Added in version 0.4.3.

class Constant

Bases: ArraySymbol

Constant symbol.

See also

constant(): equivalent method.

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 Copy

Bases: ArraySymbol

An array symbol that is a copy of another array symbol.

See also

ArraySymbol.copy() Equivalent method.

Added in version 0.5.1.

class Cos(x)

Bases: _UnaryOpSymbol

Cosine element-wise on a symbol.

See also

cos(): equivalent function.

Added in version 0.6.5.

class DisjointBitSet

Bases: ArraySymbol

Disjoint-sets successor symbol.

See also

disjoint_bit_sets(): equivalent method.

set_index()

Return the index for the set.

class DisjointBitSets

Bases: Symbol

Disjoint-sets decision-variable symbol.

See also

disjoint_bit_sets(): equivalent method.

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.

See also

disjoint_lists(): associated method.

list_index()

Return the index for the list.

class DisjointLists

Bases: Symbol

Disjoint-lists decision-variable symbol.

See also

disjoint_lists(): equivalent method.

num_disjoint_lists()

Return the number of disjoint lists in the symbol.

primary_set_size()

Return the size of primary set of elements that the lists contain.

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.

Examples

This example sets the state of a disjoint-lists symbol. You can inspect the state of each list individually.

>>> from dwave.optimization.model import Model
>>> model = Model()
>>> lists_symbol = model.disjoint_lists_symbol(
...     primary_set_size=5,
...     num_disjoint_lists=3
... )
>>> with model.lock():
...     model.states.resize(1)
...     lists_symbol.set_state(0, [[0, 1, 2, 3], [4], []])
...     for index, disjoint_list in enumerate(lists_symbol):
...         print(f"DisjointList {index}:")
...         print(disjoint_list.state(0))
DisjointList 0:
[0. 1. 2. 3.]
DisjointList 1:
[4.]
DisjointList 2:
[]

class Divide(lhs, rhs)

Bases: _BinaryOpSymbol

Division element-wise between two symbols.

class Equal(lhs, rhs)

Bases: _BinaryOpSymbol

Equality comparison element-wise between two symbols.

class Exp(x)

Bases: _UnaryOpSymbol

Takes the values of a symbol and returns the corresponding base-e exponential.

See also

exp(): equivalent function.

Added in version 0.6.2.

class Expit(x)

Bases: _UnaryOpSymbol

Takes the values of a symbol and returns the corresponding logistic sigmoid (expit).

See also

expit(): equivalent function.

Added in version 0.5.2.

class Extract

Bases: ArraySymbol

Return elements chosen from x or y depending on condition.

See also

where(): equivalent function.

class Input

Bases: ArraySymbol

An input symbol. Functions as a “placeholder” in a model.

integral()

Whether the input symbol will always output integers.

lower_bound()

Lowest value allowed to the input.

set_state(index, state)

Set the state of the input symbol.

The given state must be the same shape as the input symbol’s shape.

upper_bound()

Largest value allowed to the input.

class IntegerVariable

Bases: ArraySymbol

Integer decision-variable symbol.

See also

integer(): equivalent method.

lower_bound()

Lower bound(s) of Integer symbol.

set_state(index, state)

Set the state of the integer symbol.

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

Examples

This example successfully sets one state for a \(2 \times 2\)-sized integer symbol.

>>> from dwave.optimization.model import Model
>>> import numpy as np
...
>>> model = Model()
>>> x = model.integer((2, 2), lower_bound=2, upper_bound=[[3,4], [2, 5]])
>>> model.states.resize(1)
>>> x.set_state(0, [[3, 4], [2, 3]])
>>> print(np.equal(x.state(0), [[3, 4], [2, 3]]).all())
True

upper_bound()

Upper bound(s) of Integer symbol.

class IsIn

Bases: ArraySymbol

Determine element-wise containment between two symbols. Given two symbols: element and test_elements, returns an output array of the same shape as element such that output[index] = True if element[index] is in test_elements and False otherwise.

See also

isin(): equivalent method.

Added in version 0.6.8.

class LessEqual(lhs, rhs)

Bases: _BinaryOpSymbol

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

class LinearProgram

Bases: Symbol

Find a solution to the linear program (LP) defined by the predecessors.

See also

linprog()

Added in version 0.6.0.

state(index=0)

Return the current solution to the LP.

If the LP is not feasible, the solution is not meaningful.

class LinearProgramFeasible

Bases: ArraySymbol

Return whether the parent LP symbol’s current solution is feasible.

See also

linprog()

Added in version 0.6.0.

class LinearProgramObjectiveValue

Bases: ArraySymbol

Return the objective value of the parent LP symbol’s current solution.

See also

linprog()

Added in version 0.6.0.

class LinearProgramSolution

Bases: ArraySymbol

Return the current solution of the parent LP symbol as an array.

See also

linprog()

Added in version 0.6.0.

class ListVariable

Bases: ArraySymbol

List decision-variable symbol.

See also

list(): equivalent method.

set_state(index, values)

Set the state of the list node.

The given values must be a sub-permuation of range(n) where n is the size of the list.

class Log(x)

Bases: _UnaryOpSymbol

Takes the values of a symbol and returns the corresponding natural logarithm (log).

See also

log(): equivalent function.

Added in version 0.5.2.

class Logical(x)

Bases: _UnaryOpSymbol

Logical truth value element-wise on a symbol.

See also

logical(): equivalent function.

class Max(array, *, axis=None, initial=<no value>)

Bases: _ReduceSymbol

Maximum value in the elements of a symbol.

See also

max() equivalent method.

class Maximum(lhs, rhs)

Bases: _BinaryOpSymbol

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

class Mean

Bases: ArraySymbol

Mean value of the elements of a symbol.

If symbol is empty, the mean defaults to 0.0.

See also

mean(): equivalent method.

Added in version 0.6.4.

class Min(array, *, axis=None, initial=<no value>)

Bases: _ReduceSymbol

Minimum value in the elements of a symbol.

See also

min() equivalent method.

class Minimum(lhs, rhs)

Bases: _BinaryOpSymbol

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

class Modulus(lhs, rhs)

Bases: _BinaryOpSymbol

Modulus element-wise between two symbols.

class Multiply(lhs, rhs)

Bases: _BinaryOpSymbol

Multiplication element-wise between two symbols.

class NaryAdd

Bases: ArraySymbol

Addition element-wise of N symbols.

class NaryMaximum

Bases: ArraySymbol

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

class NaryMinimum

Bases: ArraySymbol

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

class NaryMultiply

Bases: ArraySymbol

Multiplication element-wise between N symbols.

class Negative(x)

Bases: _UnaryOpSymbol

Numerical negative element-wise on a symbol.

class Not(x)

Bases: _UnaryOpSymbol

Logical negation element-wise on a symbol.

See also

logical_not(): equivalent function.

class Or(lhs, rhs)

Bases: _BinaryOpSymbol

Boolean OR element-wise between two symbols.

See also

logical_or(): equivalent function.

PartialProd

alias of Prod

PartialSum

alias of Sum

class Permutation

Bases: ArraySymbol

Permutation of the elements of a symbol.

class Prod(array, *, axis=None, initial=<no value>)

Bases: _ReduceSymbol

Product of the elements of a symbol.

See also

prod() equivalent method.

class Put

Bases: ArraySymbol

A symbol that replaces the specified elements in an array with given values.

See also

put(): equivalent function.

Added in version 0.4.4.

class QuadraticModel

Bases: ArraySymbol

Quadratic model.

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.

See also

ArraySymbol.reshape(): equivalent method.

Added in version 0.5.1.

class Resize

Bases: ArraySymbol

Resize symbol.

See also

resize(): equivalent function.

ArraySymbol.resize(): equivalent method.

Added in version 0.6.4.

class Rint(x)

Bases: _UnaryOpSymbol

Takes the values of a symbol and rounds them to the nearest integer.

class Roll

Bases: ArraySymbol

Roll symbol.

See also

roll(): equivalent function.

Added in version 0.6.9.

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.

class SafeDivide(lhs, rhs)

Bases: _BinaryOpSymbol

Safe division element-wise between two symbols.

See also

safe_divide(): equivalent function.

Added in version 0.6.2.

class SetVariable

Bases: ArraySymbol

Set decision-variable symbol.

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

See also

set(): equivalent method.

set_state(index, values)

Set the state of the set node.

The given state must be a subset of range(n) where n is the size of the set.

class Sin(x)

Bases: _UnaryOpSymbol

Sine element-wise on a symbol.

See also

sin(): equivalent function.

Added in version 0.6.5.

class Size

Bases: ArraySymbol

class SoftMax

Bases: ArraySymbol

Softmax of a symbol.

See also

softmax(): equivalent method.

Added in version 0.6.5.

class Square(x)

Bases: _UnaryOpSymbol

Squares element-wise of a symbol.

class SquareRoot(x)

Bases: _UnaryOpSymbol

Square root of a symbol.

class Subtract(lhs, rhs)

Bases: _BinaryOpSymbol

Subtraction element-wise of two symbols.

class Sum(array, *, axis=None, initial=<no value>)

Bases: _ReduceSymbol

Sum of the elements of a symbol.

See also

sum() equivalent method.

class Transpose

Bases: ArraySymbol

Tranpose symbol.

See also

transpose(): equivalent function.

Added in version 0.6.8.

class Where

Bases: ArraySymbol

Return elements chosen from x or y depending on condition.

See also

where(): equivalent function.

class Xor(lhs, rhs)

Bases: _BinaryOpSymbol

Boolean XOR element-wise between two symbols.

See also

logical_xor(): equivalent function.

Added in version 0.4.1.