Expression

class Express[source]

Abstract class of pyqubo expression.

All basic component class such as Binary, Spin or Add inherits Express.

digraph {
    graph [size="2.5, 2.5"]
    node [shape=rl]
    add [label=AddList]
    qbit_a [label="Binary(a)"]
    qbit_b [label="Binary(b)"]
    mul_1 [label="Mul"]
    mul_2 [label="Mul"]
    num_1 [label="Num(1)"]
    num_2 [label="Num(2)"]
    add -> num_1
    add -> mul_1
    mul_1 -> mul_2
    mul_1 -> qbit_a
    mul_2 -> qbit_b
    mul_2 -> num_2
}

For example, an expression \(2ab+1\) (where \(a, b\) is Binary variable) is represented by the binary tree above.

Note

This class is an abstract class of all component of expressions.

Example

We write mathematical expressions with objects such as Binary or Spin which inherit Express.

>>> from pyqubo import Binary
>>> a, b = Binary("a"), Binary("b")
>>> 2*a*b + 1
(((Binary(a)*Num(2))*Binary(b))+Num(1))
compile(strength=5.0)[source]

Returns the compiled Model.

This method reduces the degree of the expression if the degree is higher than 2, and convert it into Model which has information about QUBO.

Parameters:strength (float) – The strength of the reduction constraint. Insufficient strength can result in the binary quadratic model not having the same minimizations as the polynomial.
Returns:The model compiled from the Express.
Return type:Model

Examples

In this example, there is a higher order term \(abcd\). It is decomposed as [[a*d, c], b] hierarchically and converted into QUBO. By calling to_qubo() of the model, we get the resulting QUBO.

>>> from pyqubo import Binary
>>> a, b, c, d = Binary("a"), Binary("b"), Binary("c"), Binary("d")
>>> model = (a*b*c + a*b*d).compile()
>>> pprint(model.to_qubo()) # doctest: +SKIP
({('a', 'a'): 0.0,
  ('a', 'a*b'): -10.0,
  ('a', 'b'): 5.0,
  ('a*b', 'a*b'): 15.0,
  ('a*b', 'b'): -10.0,
  ('a*b', 'c'): 1.0,
  ('a*b', 'd'): 1.0,
  ('b', 'b'): 0.0,
  ('c', 'c'): 0,
  ('d', 'd'): 0},
 0.0)

Binary

class Binary(label, structure=None)[source]

Binary variable i.e. {0, 1}.

Parameters:
  • label (str) – The label of a variable. A variable is identified by this label.
  • structure (dict/optional) – Variable structure.

Example

>>> from pyqubo import Binary
>>> a, b = Binary('a'), Binary('b')
>>> exp = 2*a*b + 3*a
>>> pprint(exp.compile().to_qubo())   # doctest: +SKIP
({('a', 'a'): 3.0, ('a', 'b'): 2.0, ('b', 'b'): 0}, 0.0)

Spin

class Spin(label, structure=None)[source]

Spin variable i.e. {-1, 1}.

Parameters:
  • label (str) – The label of a variable. A variable is identified by this label.
  • structure (dict/optional) – Variable structure.

Example

>>> from pyqubo import Spin
>>> a, b = Spin('a'), Spin('b')
>>> exp = 2*a*b + 3*a
>>> pprint(exp.compile().to_qubo()) # doctest: +SKIP
({('a', 'a'): 2.0, ('a', 'b'): 8.0, ('b', 'b'): -4.0}, -1.0)

Placeholder

class Placeholder(label)[source]

Placeholder expression.

You can specify the value of the Placeholder when creating the QUBO. By using Placeholder, you can change the value without compiling again. This is useful when you need to update the strength of constraint gradually.

Parameters:label (str) – The label of the placeholder.

Example

The value of the placeholder is specified when you call to_qubo().

>>> from pyqubo import Binary, Placeholder
>>> x, y, a = Binary('x'), Binary('y'), Placeholder('a')
>>> exp = a*x*y + 2.0*x
>>> pprint(exp.compile().to_qubo(feed_dict={'a': 3.0})) # doctest: +SKIP
({('x', 'x'): 2.0, ('x', 'y'): 3.0, ('y', 'y'): 0}, 0.0)
>>> pprint(exp.compile().to_qubo(feed_dict={'a': 5.0})) # doctest: +SKIP
({('x', 'x'): 2.0, ('x', 'y'): 5.0, ('y', 'y'): 0}, 0.0)

Constraint

class Constraint(child, label)[source]

Constraint expression.

You can specify the constraint part in your expression.

Parameters:
  • child (Express) – The expression you want to specify as a constraint.
  • label (str) – The label of the constraint. You can identify constraints by the label.

Example

When the solution is broken, decode_solution can detect it. In this example, we introduce a constraint \(a+b=1\).

>>> from pyqubo import Binary, Constraint
>>> a, b = Binary('a'), Binary('b')
>>> exp = a + b + Constraint((a+b-1)**2, label="one_hot")
>>> model = exp.compile()
>>> sol, broken, energy = model.decode_solution({'a': 1, 'b': 1}, vartype='BINARY')
>>> pprint(broken)
{'one_hot': {'penalty': 1.0, 'result': {'a': 1, 'b': 1}}}
>>> sol, broken, energy = model.decode_solution({'a': 1, 'b': 0}, vartype='BINARY')
>>> pprint(broken)
{}

UserDefinedExpress

class UserDefinedExpress[source]

User defined express.

User can define their own expression by inheriting UserDefinedExpress.

Example

Define the LogicalAnd class by inheriting UserDefinedExpress.

>>> from pyqubo import UserDefinedExpress
>>> class LogicalAnd(UserDefinedExpress):
...     def __init__(self, bit_a, bit_b):
...         self._express = bit_a * bit_b
...
...     @property
...     def express(self):
...         return self._express
express

Expression of the Hamiltonian defined by the user.

Type:Express

Add

class Add(left, right)[source]

Addition of expressions (deprecated).

Parameters:

Example

You can add expressions with either the built-in operator or Add.

>>> from pyqubo import Binary, Add
>>> a, b = Binary('a'), Binary('b')
>>> a + b
(Binary(a)+Binary(b))
>>> Add(a, b)
(Binary(a)+Binary(b))

AddList

class AddList(terms)[source]

Addition of a list of expressions.

Parameters:terms (list[Express]) – a list of expressions

Example

You can add expressions with either the built-in operator or AddList.

>>> from pyqubo import Binary, AddList
>>> a, b = Binary('a'), Binary('b')
>>> a + b
(Binary(a)+Binary(b))
>>> AddList([a, b])
(Binary(a)+Binary(b))

Mul

class Mul(left, right)[source]

Product of expressions.

Parameters:

Example

You can multiply expressions with either the built-in operator or Mul.

>>> from pyqubo import Binary, Mul
>>> a, b = Binary('a'), Binary('b')
>>> a * b
(Binary(a)*Binary(b))
>>> Mul(a, b)
(Binary(a)*Binary(b))

Num

class Num(value)[source]

Expression of number

Parameters:value (float) – the value of the number.

Example

>>> from pyqubo import Binary, Num
>>> a = Binary('a')
>>> a + 1
(Binary(a)+Num(1))
>>> a + Num(1)
(Binary(a)+Num(1))