Classical expressions

qiskit.circuit.classical

This module contains an exploratory representation of runtime operations on classical values during circuit execution.

Currently, only simple expressions on bits and registers that result in a Boolean value are supported, and these are only valid for use in the conditions of QuantumCircuit.if_test() (IfElseOp) and QuantumCircuit.while_loop() (WhileLoopOp), and in the target of QuantumCircuit.switch() (SwitchCaseOp).

Expressions

qiskit.circuit.classical.expr

The necessary components for building expressions are all exported from the expr namespace within qiskit.circuit.classical, so you can choose whether to use qualified access (for example expr.Value) or import the names you need directly and call them without the prefix.

There are two pathways for constructing expressions. The classes that form the representation of the expression system have constructors that perform zero type checking; it is up to the caller to ensure that they are building valid objects. For a more user-friendly interface to direct construction, there are helper functions associated with most of the classes that do type validation and inference. These are described below, in Construction.

Representation

The expression system is based on tree representation. All nodes in the tree are final (uninheritable) instances of the abstract base class:

Expr

These objects are mutable and should not be reused in a different location without a copy.

The entry point from general circuit objects to the expression system is by wrapping the object in a Var node and associating a Type with it.

Var

Similarly, literals used in comparison (such as integers) should be lifted to Value nodes with associated types.

Value

The operations traditionally associated with pre-, post- or infix operators in programming are represented by the Unary and Binary nodes as appropriate. These each take an operation type code, which are exposed as enumerations inside each class as Unary.Op and Binary.Op respectively.

Unary

Binary

When constructing expressions, one must ensure that the types are valid for the operation. Attempts to construct expressions with invalid types will raise a regular Python TypeError.

Expressions in this system are defined to act only on certain sets of types. However, values may be cast to a suitable supertype in order to satisfy the typing requirements. In these cases, a node in the expression tree is used to represent the promotion. In all cases where operations note that they “implicitly cast” or “coerce” their arguments, the expression tree must have this node representing the conversion.

Cast

Construction

Constructing the tree representation directly is verbose and easy to make a mistake with the typing. In many cases, much of the typing can be inferred, scalar values can automatically be promoted to Value instances, and any required promotions can be resolved into suitable Cast nodes.

The functions and methods described in this section are a more user-friendly way to build the expression tree, while staying close to the internal representation. All these functions will automatically lift valid Python scalar values into corresponding Var or Value objects, and will resolve any required implicit casts on your behalf. If you want to directly use some scalar value as an Expr node, you can manually lift() it yourself.

lift

>>> from qiskit.circuit import Clbit, ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.lift(Clbit())
Var(<clbit>, Bool())
>>> expr.lift(ClassicalRegister(3, "c"))
Var(ClassicalRegister(3, "c"), Uint(3))

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr, types
>>> expr.lift(ClassicalRegister(3, "c"), types.Uint(5))
Var(ClassicalRegister(3, "c"), Uint(5))
>>> expr.lift(5, types.Uint(4))
Value(5, Uint(4))

You can manually specify casts in cases where the cast is allowed in explicit form, but may be lossy (such as the cast of a higher precision Uint to a lower precision one).

cast

>>> from qiskit.circuit.classical import expr, types
>>> value = expr.value(5, types.Uint(32))
>>> expr.cast(value, types.Uint(8))
Cast(Value(5, types.Uint(32)), types.Uint(8), implicit=False)

There are helper constructor functions for each of the unary operations.

bit_not

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.bit_not(ClassicalRegister(3, "c"))
Unary(Unary.Op.BIT_NOT, Var(ClassicalRegister(3, 'c'), Uint(3)), Uint(3))

logic_not

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.logic_not(ClassicalRegister(3, "c"))
Unary(Unary.Op.LOGIC_NOT, Cast(Var(ClassicalRegister(3, 'c'), Uint(3)), Bool(), implicit=True), Bool())

Similarly, the binary operations and relations have helper functions defined.

bit_and

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.bit_and(ClassicalRegister(3, "c"), 0b111)
Binary(Binary.Op.BIT_AND, Var(ClassicalRegister(3, 'c'), Uint(3)), Value(7, Uint(3)), Uint(3))

bit_or

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.bit_or(ClassicalRegister(3, "c"), 0b101)
Binary(Binary.Op.BIT_OR, Var(ClassicalRegister(3, 'c'), Uint(3)), Value(5, Uint(3)), Uint(3))

bit_xor

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.bit_xor(ClassicalRegister(3, "c"), 0b101)
Binary(Binary.Op.BIT_XOR, Var(ClassicalRegister(3, 'c'), Uint(3)), Value(5, Uint(3)), Uint(3))

logic_and

>>> from qiskit.circuit import Clbit
>>> from qiskit.circuit.classical import expr
>>> expr.logical_and(Clbit(), Clbit())
Binary(Binary.Op.LOGIC_AND, Var(<clbit 0>, Bool()), Var(<clbit 1>, Bool()), Bool())

logic_or

>>> from qiskit.circuit import Clbit
>>> from qiskit.circuit.classical import expr
>>> expr.logical_and(Clbit(), Clbit())
Binary(Binary.Op.LOGIC_OR, Var(<clbit 0>, Bool()), Var(<clbit 1>, Bool()), Bool())

equal

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.equal(ClassicalRegister(3, "c"), 7)
Binary(Binary.Op.EQUAL, Var(ClassicalRegister(3, "c"), Uint(3)), Value(7, Uint(3)), Uint(3))

not_equal

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.not_equal(ClassicalRegister(3, "c"), 7)
Binary(Binary.Op.NOT_EQUAL, Var(ClassicalRegister(3, "c"), Uint(3)), Value(7, Uint(3)), Uint(3))

less

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.less(ClassicalRegister(3, "c"), 5)
Binary(Binary.Op.LESS, Var(ClassicalRegister(3, "c"), Uint(3)), Value(5, Uint(3)), Uint(3))

less_equal

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.less(ClassicalRegister(3, "a"), ClassicalRegister(3, "b"))
Binary(Binary.Op.LESS_EQUAL, Var(ClassicalRegister(3, "a"), Uint(3)), Var(ClassicalRegister(3, "b"), Uint(3)), Uint(3))

greater

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.less(ClassicalRegister(3, "c"), 5)
Binary(Binary.Op.GREATER, Var(ClassicalRegister(3, "c"), Uint(3)), Value(5, Uint(3)), Uint(3))

greater_equal

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.less(ClassicalRegister(3, "a"), ClassicalRegister(3, "b"))
Binary(Binary.Op.GREATER_EQUAL, Var(ClassicalRegister(3, "a"), Uint(3)), Var(ClassicalRegister(3, "b"), Uint(3)), Uint(3))

Qiskit’s legacy method for specifying equality conditions for use in conditionals is to use a two-tuple of a Clbit or ClassicalRegister and an integer. This represents an exact equality condition, and there are no ways to specify any other relations. The helper function lift_legacy_condition() converts this legacy format into the new expression syntax.

lift_legacy_condition

from qiskit.circuit import ClassicalRegister
from qiskit.circuit.library import HGate
from qiskit.circuit.classical import expr
 
cr = ClassicalRegister(2)
instr = HGate().c_if(cr, 3)
 
lifted = expr.lift_legacy_condition(instr.condition)

Working with the expression tree

A typical consumer of the expression tree wants to recursively walk through the tree, potentially statefully, acting on each node differently depending on its type. This is naturally a double-dispatch problem; the logic of ‘what is to be done’ is likely stateful and users should be free to define their own operations, yet each node defines ‘what is being acted on’. We enable this double dispatch by providing a base visitor class for the expression tree.

ExprVisitor

Consumers of the expression tree should subclass the visitor, and override the visit_* methods that they wish to handle. Any non-overridden methods will call visit_generic(), which unless overridden will raise a RuntimeError to ensure that you are aware if new nodes have been added to the expression tree that you are not yet handling.

For the convenience of simple visitors that only need to inspect the variables in an expression and not the general structure, the iterator method iter_vars() is provided.

iter_vars

from qiskit.circuit import ClassicalRegister
from qiskit.circuit.classical import expr
 
cr1 = ClassicalRegister(3, "a")
cr2 = ClassicalRegister(3, "b")
 
for node in expr.iter_vars(expr.bit_and(expr.bit_not(cr1), cr2)):
    if isinstance(node.var, ClassicalRegister):
        print(node.var.name)

Two expressions can be compared for direct structural equality by using the built-in Python == operator. In general, though, one might want to compare two expressions slightly more semantically, allowing that the Var nodes inside them are bound to different memory-location descriptions between two different circuits. In this case, one can use structurally_equivalent() with two suitable “key” functions to do the comparison.

structurally_equivalent

>>> from qiskit.circuit import Clbit
>>> from qiskit.circuit.classical import expr
>>> left_bits = [Clbit(), Clbit()]
>>> right_bits = [Clbit(), Clbit()]
>>> left = expr.logic_and(expr.logic_not(left_bits[0]), left_bits[1])
>>> right = expr.logic_and(expr.logic_not(right_bits[0]), right_bits[1])
>>> expr.structurally_equivalent(left, right)
False

>>> left_key = {var: i for i, var in enumerate(left_bits)}.get
>>> right_key = {var: i for i, var in enumerate(right_bits)}.get
>>> expr.structurally_equivalent(left, right, left_key, right_key)
True

Typing

qiskit.circuit.classical.types

Representation

The type system of the expression tree is exposed through this module. This is inherently linked to the expression system in the expr module, as most expressions can only be understood with the context of the types that they act on.

All types inherit from an abstract base class:

Type

Types should be considered immutable objects, and you must not mutate them. It is permissible to reuse a Type that you take from another object without copying it, and generally this will be the best approach for performance. Type objects are designed to be small amounts of data, and it’s best to point to the same instance of the data where possible rather than heap-allocating a new version of the same thing. Where possible, the class constructors will return singleton instances to facilitate this.

The two different types available are for Booleans (corresponding to Clbit and the literals True and False), and unsigned integers (corresponding to ClassicalRegister and Python integers).

Bool

Uint

Note that Uint defines a family of types parametrised by their width; it is not one single type, which may be slightly different to the ‘classical’ programming languages you are used to.

Working with types

There are some functions on these types exposed here as well. These are mostly expected to be used only in manipulations of the expression tree; users who are building expressions using the user-facing construction interface should not need to use these.

Partial ordering of types

The type system is equipped with a partial ordering, where $a < b$ is interpreted as “$a$ is a strict subtype of $b$”. Note that the partial ordering is a subset of the directed graph that describes the allowed explicit casting operations between types. The partial ordering defines when one type may be lossless directly interpreted as another.

The low-level interface to querying the subtyping relationship is the order() function.

order

>>> from qiskit.circuit.classical import types
>>> types.order(types.Uint(8), types.Uint(16))
Ordering.LESS

>>> types.order(types.Uint(8), types.Bool())
Ordering.NONE

The return value is an enumeration Ordering that describes what, if any, subtyping relationship exists between the two types.

Ordering

Some helper methods are then defined in terms of this low-level order() primitive:

is_subtype

>>> from qiskit.circuit.classical import types
>>> types.is_subtype(types.Uint(8), types.Uint(16))
True

>>> types.is_subtype(types.Bool(), types.Bool())
True
>>> types.is_subtype(types.Bool(), types.Bool(), strict=True)
False

is_supertype

>>> from qiskit.circuit.classical import types
>>> types.is_supertype(types.Uint(8), types.Uint(16))
False

>>> types.is_supertype(types.Bool(), types.Bool())
True
>>> types.is_supertype(types.Bool(), types.Bool(), strict=True)
False

greater

>>> from qiskit.circuit.classical import types
>>> types.greater(types.Uint(8), types.Uint(16))
types.Uint(16)

Casting between types

It is common to need to cast values of one type to another type. The casting rules for this are embedded into the types(opens in a new tab) module. You can query the casting kinds using cast_kind():

cast_kind

>>> from qiskit.circuit.classical import types
>>> types.cast_kind(types.Bool(), types.Bool())
<CastKind.EQUAL: 1>
>>> types.cast_kind(types.Uint(8), types.Bool())
<CastKind.IMPLICIT: 2>
>>> types.cast_kind(types.Bool(), types.Uint(8))
<CastKind.LOSSLESS: 3>
>>> types.cast_kind(types.Uint(16), types.Uint(8))
<CastKind.DANGEROUS: 4>

The return values from this function are an enumeration explaining the types of cast that are allowed from the left type to the right type.

CastKind