Classical expressions

qiskit.circuit.classical.expr.lift(value, /, type=None)

Lift the given Python value to a Value or Var.

If an explicit type is given, the typing in the output will reflect that.

Examples

Lifting simple circuit objects to be Var instances:

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

The type of the return value can be influenced, if the given value could be interpreted losslessly as the given type (use cast() to perform a full set of casting operations, include lossy ones):

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

Parameters

• value (Any) –
• type (types.Type | None) –

Return type

Expr

qiskit.circuit.classical.expr.cast(operand, type, /)

Create an explicit cast from the given value to the given type.

Examples

Add an explicit cast node that explicitly casts a higher precision type to a lower precision one:

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

Parameters

• operand (Any) –
• type (Type) –

Return type

Expr

qiskit.circuit.classical.expr.bit_not(operand, /)

Create a bitwise ‘not’ expression node from the given value, resolving any implicit casts and lifting the value into a Value node if required.

Examples

Bitwise negation of a ClassicalRegister:

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

Parameters

operand (Any) –

Return type

Expr

qiskit.circuit.classical.expr.logic_not(operand, /)

Create a logical ‘not’ expression node from the given value, resolving any implicit casts and lifting the value into a Value node if required.

Examples

Logical negation of a ClassicalRegister:

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

Parameters

operand (Any) –

Return type

Expr

qiskit.circuit.classical.expr.bit_and(left, right, /)

Create a bitwise ‘and’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Bitwise ‘and’ of a classical register and an integer literal:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.bit_or(left, right, /)

Create a bitwise ‘or’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Bitwise ‘or’ of a classical register and an integer literal:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.bit_xor(left, right, /)

Create a bitwise ‘exclusive or’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Bitwise ‘exclusive or’ of a classical register and an integer literal:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.logic_and(left, right, /)

Create a logical ‘and’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Logical ‘and’ of two classical bits:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.logic_or(left, right, /)

Create a logical ‘or’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Logical ‘or’ of two classical bits

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.equal(left, right, /)

Create an ‘equal’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Equality between a classical register and an integer:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.not_equal(left, right, /)

Create a ‘not equal’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Inequality between a classical register and an integer:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.less(left, right, /)

Create a ‘less than’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Query if a classical register is less than an integer:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.less_equal(left, right, /)

Create a ‘less than or equal to’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Query if a classical register is less than or equal to another:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.greater(left, right, /)

Create a ‘greater than’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Query if a classical register is greater than an integer:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.greater_equal(left, right, /)

Create a ‘greater than or equal to’ expression node from the given value, resolving any implicit casts and lifting the values into Value nodes if required.

Examples

Query if a classical register is greater than or equal to another:

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

Parameters

• left (Any) –
• right (Any) –

Return type

Expr

qiskit.circuit.classical.expr.shift_left(left, right, /, type=None)

Create a ‘bitshift left’ expression node from the given two values, resolving any implicit casts and lifting the values into Value nodes if required.

If type is given, the left operand will be coerced to it (if possible).

Examples

Shift the value of a standalone variable left by some amount:

>>> from qiskit.circuit.classical import expr, types
>>> a = expr.Var.new("a", types.Uint(8))
>>> expr.shift_left(a, 4)
Binary(Binary.Op.SHIFT_LEFT, Var(<UUID>, Uint(8), name='a'), Value(4, Uint(3)), Uint(8))

Shift an integer literal by a variable amount, coercing the type of the literal:

>>> expr.shift_left(3, a, types.Uint(16))
Binary(Binary.Op.SHIFT_LEFT, Value(3, Uint(16)), Var(<UUID>, Uint(8), name='a'), Uint(16))

Parameters

• left (Any) –
• right (Any) –
• type (types.Type | None) –

Return type

Expr

qiskit.circuit.classical.expr.shift_right(left, right, /, type=None)

Create a ‘bitshift right’ expression node from the given values, resolving any implicit casts and lifting the values into Value nodes if required.

If type is given, the left operand will be coerced to it (if possible).

Examples

Shift the value of a classical register right by some amount:

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.shift_right(ClassicalRegister(8, "a"), 4)
Binary(Binary.Op.SHIFT_RIGHT, Var(ClassicalRegister(8, "a"), Uint(8)), Value(4, Uint(3)), Uint(8))

Parameters

• left (Any) –
• right (Any) –
• type (types.Type | None) –

Return type

Expr

qiskit.circuit.classical.expr.index(target, index, /)

Index into the target with the given integer index, lifting the values into Value nodes if required.

This can be used as the target of a Store, if the target is itself an lvalue.

Examples

Index into a classical register with a literal:

>>> from qiskit.circuit import ClassicalRegister
>>> from qiskit.circuit.classical import expr
>>> expr.index(ClassicalRegister(8, "a"), 3)
Index(Var(ClassicalRegister(8, "a"), Uint(8)), Value(3, Uint(2)), Bool())

Parameters

• target (Any) –
• index (Any) –

Return type

Expr

qiskit.circuit.classical.expr.lift_legacy_condition(condition, /)

Lift a legacy two-tuple equality condition into a new-style Expr.

Examples

Taking an old-style conditional instruction and getting an Expr from its 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)

Parameters

condition (tuple[qiskit.circuit.Clbit |qiskit.circuit.ClassicalRegister, int]) –

Return type

Expr

qiskit.circuit.classical.expr.iter_vars(node)

Get an iterator over the Var nodes referenced at any level in the given Expr.

Examples

Print out the name of each ClassicalRegister encountered:

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)

Parameters

node (Expr) –

Return type

Iterator[Var]

qiskit.circuit.classical.expr.structurally_equivalent(left, right, left_var_key=None, right_var_key=None)

Do these two expressions have exactly the same tree structure, up to some key function for the Var objects?

In other words, are these two expressions the exact same trees, except we compare the Var.var fields by calling the appropriate *_var_key function on them, and comparing that output for equality. This function does not allow any semantic “equivalences” such as asserting that a == b is equivalent to b == a; the evaluation order of the operands could, in general, cause such a statement to be false (consider hypothetical extern functions that access global state).

There’s no requirements on the key functions, except that their outputs should have general __eq__ methods. If a key function returns None, the variable will be used verbatim instead.

Parameters

• left (expr.Expr) – one of the Expr nodes.
• right (expr.Expr) – the other Expr node.
• left_var_key (Callable[[Any], Any] | None) – a callable whose output should be used when comparing Var.var attributes. If this argument is None or its output is None for a given variable in left, the variable will be used verbatim.
• right_var_key (Callable[[Any], Any] | None) – same as left_var_key, but used on the variables in right instead.

Return type

bool

Examples

Comparing two expressions for structural equivalence, with no remapping of the variables. These are different because the different Clbit instances compare differently:

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

Comparing the same two expressions, but this time using mapping functions that associate the bits with simple indices:

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

qiskit.circuit.classical.expr.is_lvalue(node, /)

Return whether this expression can be used in l-value positions, that is, whether it has a well-defined location in memory, such as one that might be writeable.

Being an l-value is a necessary but not sufficient for this location to be writeable; it is permissible that a larger object containing this memory location may not allow writing from the scope that attempts to write to it. This would be an access property of the containing program, however, and not an inherent property of the expression system.

Examples

Literal values are never l-values; there’s no memory location associated with (for example) the constant 1:

>>> from qiskit.circuit.classical import expr
>>> expr.is_lvalue(expr.lift(2))
False

Var nodes are always l-values, because they always have some associated memory location:

>>> from qiskit.circuit.classical import types
>>> from qiskit.circuit import Clbit
>>> expr.is_lvalue(expr.Var.new("a", types.Bool()))
True
>>> expr.is_lvalue(expr.lift(Clbit()))
True

Currently there are no unary or binary operations on variables that can produce an l-value expression, but it is likely in the future that some sort of “indexing” operation will be added, which could produce l-values:

>>> a = expr.Var.new("a", types.Uint(8))
>>> b = expr.Var.new("b", types.Uint(8))
>>> expr.is_lvalue(a) and expr.is_lvalue(b)
True
>>> expr.is_lvalue(expr.bit_and(a, b))
False

Parameters

node (Expr) –

Return type

bool

qiskit.circuit.classical.types.order(left, right, /)

Get the ordering relationship between the two types as an enumeration value.

Examples

Compare two Uint types of different widths:

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

Compare two types that have no ordering between them:

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

Parameters

• left (Type) –
• right (Type) –

Return type

Ordering

qiskit.circuit.classical.types.is_subtype(left, right, /, strict=False)

Does the relation $\text{left} \le \text{right}$ hold? If there is no ordering relation between the two types, then this returns False. If strict, then the equality is also forbidden.

Examples

Check if one type is a subclass of another:

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

Check if one type is a strict subclass of another:

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

Parameters

• left (Type) –
• right (Type) –
• strict (bool) –

Return type

bool

qiskit.circuit.classical.types.is_supertype(left, right, /, strict=False)

Does the relation $\text{left} \ge \text{right}$ hold? If there is no ordering relation between the two types, then this returns False. If strict, then the equality is also forbidden.

Examples

Check if one type is a superclass of another:

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

Check if one type is a strict superclass of another:

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

Parameters

• left (Type) –
• right (Type) –
• strict (bool) –

Return type

bool

qiskit.circuit.classical.types.greater(left, right, /)

Get the greater of the two types, assuming that there is an ordering relation between them. Technically, this is a slightly restricted version of the concept of the ‘meet’ of the two types in that the return value must be one of the inputs. In practice in the type system there is no concept of a ‘sum’ type, so the ‘meet’ exists if and only if there is an ordering between the two types, and is equal to the greater of the two types.

Returns

The greater of the two types.

Raises

TypeError – if there is no ordering relation between the two types.

Parameters

• left (Type) –
• right (Type) –

Return type

Type

Examples

Find the greater of two Uint types:

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

qiskit.circuit.classical.types.cast_kind(from_, to_, /)

Determine the sort of cast that is required to move from the left type to the right type.

Examples

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

Parameters

• from_ (Type) –
• to_ (Type) –

Return type

CastKind