qiskit 1.0.2__cp38-abi3-macosx_10_9_universal2.whl → 1.1.0rc1__cp38-abi3-macosx_10_9_universal2.whl

qiskit/circuit/_classical_resource_map.py

@@ -37,17 +37,20 @@ class VariableMapper(expr.ExprVisitor[expr.Expr]):
     ``ValueError`` will be raised instead.  The given ``add_register`` callable may choose to raise
     its own exception."""
 
-    __slots__ = ("target_cregs", "register_map", "bit_map", "add_register")
+    __slots__ = ("target_cregs", "register_map", "bit_map", "var_map", "add_register")
 
     def __init__(
         self,
         target_cregs: typing.Iterable[ClassicalRegister],
         bit_map: typing.Mapping[Bit, Bit],
+        var_map: typing.Mapping[expr.Var, expr.Var] | None = None,
+        *,
         add_register: typing.Callable[[ClassicalRegister], None] | None = None,
     ):
         self.target_cregs = tuple(target_cregs)
         self.register_map = {}
         self.bit_map = bit_map
+        self.var_map = var_map or {}
         self.add_register = add_register
 
     def _map_register(self, theirs: ClassicalRegister) -> ClassicalRegister:
@@ -110,8 +113,8 @@ class VariableMapper(expr.ExprVisitor[expr.Expr]):
         return (mapped_theirs, mapped_value)
 
     def map_target(self, target, /):
-        """Map the runtime variables in a ``target`` of a :class:`.SwitchCaseOp` to the new circuit,
-        as defined in the ``circuit`` argument of the initialiser of this class."""
+        """Map the real-time variables in a ``target`` of a :class:`.SwitchCaseOp` to the new
+        circuit, as defined in the ``circuit`` argument of the initialiser of this class."""
         if isinstance(target, Clbit):
             return self.bit_map[target]
         if isinstance(target, ClassicalRegister):
@@ -127,9 +130,7 @@ class VariableMapper(expr.ExprVisitor[expr.Expr]):
             return expr.Var(self.bit_map[node.var], node.type)
         if isinstance(node.var, ClassicalRegister):
             return expr.Var(self._map_register(node.var), node.type)
-        # Defensive against the expansion of the variable system; we don't want to silently do the
-        # wrong thing (which would be `return node` without mapping, right now).
-        raise RuntimeError(f"unhandled variable in 'compose': {node}")  # pragma: no cover
+        return self.var_map.get(node, node)
 
     def visit_value(self, node, /):
         return expr.Value(node.value, node.type)

qiskit/circuit/_utils.py

@@ -13,7 +13,10 @@
 This module contains utility functions for circuits.
 """
 
+import math
 import numpy
+
+from qiskit import _numpy_compat
 from qiskit.exceptions import QiskitError
 from qiskit.circuit.exceptions import CircuitError
 from .parametervector import ParameterVectorElement
@@ -56,7 +59,7 @@ def _compute_control_matrix(base_mat, num_ctrl_qubits, ctrl_state=None):
     Raises:
         QiskitError: unrecognized mode or invalid ctrl_state
     """
-    num_target = int(numpy.log2(base_mat.shape[0]))
+    num_target = int(math.log2(base_mat.shape[0]))
     ctrl_dim = 2**num_ctrl_qubits
     ctrl_grnd = numpy.repeat([[1], [0]], [1, ctrl_dim - 1])
     if ctrl_state is None:
@@ -116,8 +119,9 @@ def with_gate_array(base_array):
     nonwritable = numpy.array(base_array, dtype=numpy.complex128)
     nonwritable.setflags(write=False)
 
-    def __array__(_self, dtype=None):
-        return numpy.asarray(nonwritable, dtype=dtype)
+    def __array__(_self, dtype=None, copy=_numpy_compat.COPY_ONLY_IF_NEEDED):
+        dtype = nonwritable.dtype if dtype is None else dtype
+        return numpy.array(nonwritable, dtype=dtype, copy=copy)
 
     def decorator(cls):
         if hasattr(cls, "__array__"):
@@ -148,15 +152,21 @@ def with_controlled_gate_array(base_array, num_ctrl_qubits, cached_states=None):
     if cached_states is None:
         nonwritables = [matrix_for_control_state(state) for state in range(2**num_ctrl_qubits)]
 
-        def __array__(self, dtype=None):
-            return numpy.asarray(nonwritables[self.ctrl_state], dtype=dtype)
+        def __array__(self, dtype=None, copy=_numpy_compat.COPY_ONLY_IF_NEEDED):
+            arr = nonwritables[self.ctrl_state]
+            dtype = arr.dtype if dtype is None else dtype
+            return numpy.array(arr, dtype=dtype, copy=copy)
 
     else:
         nonwritables = {state: matrix_for_control_state(state) for state in cached_states}
 
-        def __array__(self, dtype=None):
-            if (out := nonwritables.get(self.ctrl_state)) is not None:
-                return numpy.asarray(out, dtype=dtype)
+        def __array__(self, dtype=None, copy=_numpy_compat.COPY_ONLY_IF_NEEDED):
+            if (arr := nonwritables.get(self.ctrl_state)) is not None:
+                dtype = arr.dtype if dtype is None else dtype
+                return numpy.array(arr, dtype=dtype, copy=copy)
+
+            if copy is False and copy is not _numpy_compat.COPY_ONLY_IF_NEEDED:
+                raise ValueError("could not produce matrix without calculation")
             return numpy.asarray(
                 _compute_control_matrix(base, num_ctrl_qubits, self.ctrl_state), dtype=dtype
             )

qiskit/circuit/annotated_operation.py

@@ -97,7 +97,10 @@ class AnnotatedOperation(Operation):
         inverted and then controlled by 2 qubits.
         """
         self.base_op = base_op
+        """The base operation that the modifiers in this annotated operation applies to."""
         self.modifiers = modifiers if isinstance(modifiers, List) else [modifiers]
+        """Ordered sequence of the modifiers to apply to :attr:`base_op`.  The modifiers are applied
+        in order from lowest index to highest index."""
 
     @property
     def name(self):
@@ -198,6 +201,24 @@ class AnnotatedOperation(Operation):
         extended_modifiers.append(InverseModifier())
         return AnnotatedOperation(self.base_op, extended_modifiers)
 
+    def power(self, exponent: float, annotated: bool = False):
+        """
+        Raise this gate to the power of ``exponent``.
+
+        Implemented as an annotated operation, see  :class:`.AnnotatedOperation`.
+
+        Args:
+            exponent: the power to raise the gate to
+            annotated: ignored (used for consistency with other power methods)
+
+        Returns:
+            An operation implementing ``gate^exponent``
+        """
+        # pylint: disable=unused-argument
+        extended_modifiers = self.modifiers.copy()
+        extended_modifiers.append(PowerModifier(exponent))
+        return AnnotatedOperation(self.base_op, extended_modifiers)
+
 
 def _canonicalize_modifiers(modifiers):
     """

qiskit/circuit/barrier.py

@@ -16,29 +16,26 @@ Can be applied to a :class:`~qiskit.circuit.QuantumCircuit`
 with the :meth:`~qiskit.circuit.QuantumCircuit.barrier` method.
 """
 
+from __future__ import annotations
+
 from qiskit.exceptions import QiskitError
 from .instruction import Instruction
 
 
 class Barrier(Instruction):
-    """Barrier instruction.
+    """A directive for circuit compilation to separate pieces of a circuit so that any optimizations
+    or re-writes are constrained to only act between barriers.
 
-    A barrier is a visual indicator of the grouping of a circuit section.
-    It also acts as a directive for circuit compilation to separate pieces
-    of a circuit so that any optimizations or re-writes are constrained
-    to only act between barriers."""
+    This will also appear in visualizations as a visual marker.
+    """
 
     _directive = True
 
-    def __init__(self, num_qubits, label=None):
-        """Create new barrier instruction.
-
+    def __init__(self, num_qubits: int, label: str | None = None):
+        """
         Args:
-            num_qubits (int): the number of qubits for the barrier type [Default: 0].
-            label (str): the barrier label
-
-        Raises:
-            TypeError: if barrier label is invalid.
+            num_qubits: the number of qubits for the barrier.
+            label: the optional label of this barrier.
         """
         self._label = label
         super().__init__("barrier", num_qubits, 0, [], label=label)

qiskit/circuit/bit.py

@@ -24,7 +24,6 @@ class Bit:
     .. note::
         This class should not be instantiated directly. This is just a superclass
         for :class:`~.Clbit` and :class:`~.circuit.Qubit`.
-
     """
 
     __slots__ = {"_register", "_index", "_hash", "_repr"}

qiskit/circuit/classical/__init__.py

@@ -15,8 +15,8 @@
 Classical expressions (:mod:`qiskit.circuit.classical`)
 =======================================================
 
-This module contains an exploratory representation of runtime operations on classical values during
-circuit execution.
+This module contains an exploratory representation of real-time 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 :meth:`.QuantumCircuit.if_test`

qiskit/circuit/classical/expr/__init__.py

@@ -39,12 +39,13 @@ The expression system is based on tree representation.  All nodes in the tree ar
 
 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 :class:`Var` node and associating a :class:`~.types.Type` with it.
+The base for dynamic variables is the :class:`Var`, which can be either an arbitrarily typed
+real-time variable, or a wrapper around a :class:`.Clbit` or :class:`.ClassicalRegister`.
 
 .. autoclass:: Var
+    :members: var, name
 
-Similarly, literals used in comparison (such as integers) should be lifted to :class:`Value` nodes
+Similarly, literals used in expressions (such as integers) should be lifted to :class:`Value` nodes
 with associated types.
 
 .. autoclass:: Value
@@ -61,6 +62,12 @@ and :class:`Binary.Op` respectively.
     :members: Op
     :member-order: bysource
 
+Bit-like types (unsigned integers) can be indexed by integer types, represented by :class:`Index`.
+The result is a single bit.  The resulting expression has an associated memory location (and so can
+be used as an lvalue for :class:`.Store`, etc) if the target is also an lvalue.
+
+.. autoclass:: Index
+
 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``.
 
@@ -91,6 +98,13 @@ some scalar value as an :class:`Expr` node, you can manually :func:`lift` it you
 
 .. autofunction:: lift
 
+Typically you should create memory-owning :class:`Var` instances by using the
+:meth:`.QuantumCircuit.add_var` method to declare them in some circuit context, since a
+:class:`.QuantumCircuit` will not accept an :class:`Expr` that contains variables that are not
+already declared in it, since it needs to know how to allocate the storage and how the variable will
+be initialized.  However, should you want to do this manually, you should use the low-level
+:meth:`Var.new` call to safely generate a named variable for usage.
+
 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 :class:`~.types.Uint` to a lower precision one).
 
@@ -114,6 +128,13 @@ Similarly, the binary operations and relations have helper functions defined.
 .. autofunction:: less_equal
 .. autofunction:: greater
 .. autofunction:: greater_equal
+.. autofunction:: shift_left
+.. autofunction:: shift_right
+
+You can index into unsigned integers and bit-likes using another unsigned integer of any width.
+This includes in storing operations, if the target of the index is writeable.
+
+.. autofunction:: index
 
 Qiskit's legacy method for specifying equality conditions for use in conditionals is to use a
 two-tuple of a :class:`.Clbit` or :class:`.ClassicalRegister` and an integer.  This represents an
@@ -152,6 +173,11 @@ between two different circuits.  In this case, one can use :func:`structurally_e
 suitable "key" functions to do the comparison.
 
 .. autofunction:: structurally_equivalent
+
+Some expressions have associated memory locations, and others may be purely temporary.
+You can use :func:`is_lvalue` to determine whether an expression has an associated memory location.
+
+.. autofunction:: is_lvalue
 """
 
 __all__ = [
@@ -161,9 +187,11 @@ __all__ = [
     "Cast",
     "Unary",
     "Binary",
+    "Index",
     "ExprVisitor",
     "iter_vars",
     "structurally_equivalent",
+    "is_lvalue",
     "lift",
     "cast",
     "bit_not",
@@ -171,6 +199,8 @@ __all__ = [
     "bit_and",
     "bit_or",
     "bit_xor",
+    "shift_left",
+    "shift_right",
     "logic_and",
     "logic_or",
     "equal",
@@ -179,11 +209,12 @@ __all__ = [
     "less_equal",
     "greater",
     "greater_equal",
+    "index",
     "lift_legacy_condition",
 ]
 
-from .expr import Expr, Var, Value, Cast, Unary, Binary
-from .visitors import ExprVisitor, iter_vars, structurally_equivalent
+from .expr import Expr, Var, Value, Cast, Unary, Binary, Index
+from .visitors import ExprVisitor, iter_vars, structurally_equivalent, is_lvalue
 from .constructors import (
     lift,
     cast,
@@ -200,5 +231,8 @@ from .constructors import (
     less_equal,
     greater,
     greater_equal,
+    shift_left,
+    shift_right,
+    index,
     lift_legacy_condition,
 )

qiskit/circuit/classical/expr/constructors.py

@@ -37,7 +37,7 @@ __all__ = [
 
 import typing
 
-from .expr import Expr, Var, Value, Unary, Binary, Cast
+from .expr import Expr, Var, Value, Unary, Binary, Cast, Index
 from ..types import CastKind, cast_kind
 from .. import types
 
@@ -471,3 +471,86 @@ Var(ClassicalRegister(3, "b"), Uint(3)), \
 Uint(3))
     """
     return _binary_relation(Binary.Op.GREATER_EQUAL, left, right)
+
+
+def _shift_like(
+    op: Binary.Op, left: typing.Any, right: typing.Any, type: types.Type | None
+) -> Expr:
+    if type is not None and type.kind is not types.Uint:
+        raise TypeError(f"type '{type}' is not a valid bitshift operand type")
+    if isinstance(left, Expr):
+        left = _coerce_lossless(left, type) if type is not None else left
+    else:
+        left = lift(left, type)
+    right = lift(right)
+    if left.type.kind != types.Uint or right.type.kind != types.Uint:
+        raise TypeError(f"invalid types for '{op}': '{left.type}' and '{right.type}'")
+    return Binary(op, left, right, left.type)
+
+
+def shift_left(left: typing.Any, right: typing.Any, /, type: types.Type | None = None) -> Expr:
+    """Create a 'bitshift left' expression node from the given two values, resolving any implicit
+    casts and lifting the values into :class:`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))
+    """
+    return _shift_like(Binary.Op.SHIFT_LEFT, left, right, type)
+
+
+def shift_right(left: typing.Any, right: typing.Any, /, type: types.Type | None = None) -> Expr:
+    """Create a 'bitshift right' expression node from the given values, resolving any implicit casts
+    and lifting the values into :class:`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))
+    """
+    return _shift_like(Binary.Op.SHIFT_RIGHT, left, right, type)
+
+
+def index(target: typing.Any, index: typing.Any, /) -> Expr:
+    """Index into the ``target`` with the given integer ``index``, lifting the values into
+    :class:`Value` nodes if required.
+
+    This can be used as the target of a :class:`.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())
+    """
+    target, index = lift(target), lift(index)
+    if target.type.kind is not types.Uint or index.type.kind is not types.Uint:
+        raise TypeError(f"invalid types for indexing: '{target.type}' and '{index.type}'")
+    return Index(target, index, types.Bool())

qiskit/circuit/classical/expr/expr.py

@@ -31,6 +31,7 @@ __all__ = [
 import abc
 import enum
 import typing
+import uuid
 
 from .. import types
 
@@ -110,29 +111,49 @@ class Cast(Expr):
 class Var(Expr):
     """A classical variable.
 
+    These variables take two forms: a new-style variable that owns its storage location and has an
+    associated name; and an old-style variable that wraps a :class:`.Clbit` or
+    :class:`.ClassicalRegister` instance that is owned by some containing circuit.  In general,
+    construction of variables for use in programs should use :meth:`Var.new` or
+    :meth:`.QuantumCircuit.add_var`.
+
     Variables are immutable after construction, so they can be used as dictionary keys."""
 
-    __slots__ = ("var",)
+    __slots__ = ("var", "name")
 
-    var: qiskit.circuit.Clbit | qiskit.circuit.ClassicalRegister
+    var: qiskit.circuit.Clbit | qiskit.circuit.ClassicalRegister | uuid.UUID
     """A reference to the backing data storage of the :class:`Var` instance.  When lifting
     old-style :class:`.Clbit` or :class:`.ClassicalRegister` instances into a :class:`Var`,
-    this is exactly the :class:`.Clbit` or :class:`.ClassicalRegister`."""
+    this is exactly the :class:`.Clbit` or :class:`.ClassicalRegister`.  If the variable is a
+    new-style classical variable (one that owns its own storage separate to the old
+    :class:`.Clbit`/:class:`.ClassicalRegister` model), this field will be a :class:`~uuid.UUID`
+    to uniquely identify it."""
+    name: str | None
+    """The name of the variable.  This is required to exist if the backing :attr:`var` attribute
+    is a :class:`~uuid.UUID`, i.e. if it is a new-style variable, and must be ``None`` if it is
+    an old-style variable."""
 
     def __init__(
         self,
-        var: qiskit.circuit.Clbit | qiskit.circuit.ClassicalRegister,
+        var: qiskit.circuit.Clbit | qiskit.circuit.ClassicalRegister | uuid.UUID,
         type: types.Type,
+        *,
+        name: str | None = None,
     ):
         super().__setattr__("type", type)
         super().__setattr__("var", var)
+        super().__setattr__("name", name)
+
+    @classmethod
+    def new(cls, name: str, type: types.Type) -> typing.Self:
+        """Generate a new named variable that owns its own backing storage."""
+        return cls(uuid.uuid4(), type, name=name)
 
     @property
     def standalone(self) -> bool:
-        """Whether this :class:`Var` is a standalone variable that owns its storage location.
-        This is currently always ``False``, but will expand in the future to support memory-owning
-        storage locations."""
-        return False
+        """Whether this :class:`Var` is a standalone variable that owns its storage location.  If
+        false, this is a wrapper :class:`Var` around a pre-existing circuit object."""
+        return isinstance(self.var, uuid.UUID)
 
     def accept(self, visitor, /):
         return visitor.visit_var(self)
@@ -143,21 +164,29 @@ class Var(Expr):
         raise AttributeError(f"'Var' object has no attribute '{key}'")
 
     def __hash__(self):
-        return hash((self.type, self.var))
+        return hash((self.type, self.var, self.name))
 
     def __eq__(self, other):
-        return isinstance(other, Var) and self.type == other.type and self.var == other.var
+        return (
+            isinstance(other, Var)
+            and self.type == other.type
+            and self.var == other.var
+            and self.name == other.name
+        )
 
     def __repr__(self):
-        return f"Var({self.var}, {self.type})"
+        if self.name is None:
+            return f"Var({self.var}, {self.type})"
+        return f"Var({self.var}, {self.type}, name='{self.name}')"
 
     def __getstate__(self):
-        return (self.var, self.type)
+        return (self.var, self.type, self.name)
 
     def __setstate__(self, state):
-        var, type = state
+        var, type, name = state
         super().__setattr__("type", type)
         super().__setattr__("var", var)
+        super().__setattr__("name", name)
 
     def __copy__(self):
         # I am immutable...
@@ -271,6 +300,11 @@ class Binary(Expr):
         The binary mathematical relations :data:`EQUAL`, :data:`NOT_EQUAL`, :data:`LESS`,
         :data:`LESS_EQUAL`, :data:`GREATER` and :data:`GREATER_EQUAL` take unsigned integers
         (with an implicit cast to make them the same width), and return a Boolean.
+
+        The bitshift operations :data:`SHIFT_LEFT` and :data:`SHIFT_RIGHT` can take bit-like
+        container types (e.g. unsigned integers) as the left operand, and any integer type as the
+        right-hand operand.  In all cases, the output bit width is the same as the input, and zeros
+        fill in the "exposed" spaces.
         """
 
         # If adding opcodes, remember to add helper constructor functions in `constructors.py`
@@ -298,6 +332,10 @@ class Binary(Expr):
         """Numeric greater than. ``lhs > rhs``."""
         GREATER_EQUAL = 11
         """Numeric greater than or equal to. ``lhs >= rhs``."""
+        SHIFT_LEFT = 12
+        """Zero-padding bitshift to the left.  ``lhs << rhs``."""
+        SHIFT_RIGHT = 13
+        """Zero-padding bitshift to the right.  ``lhs >> rhs``."""
 
         def __str__(self):
             return f"Binary.{super().__str__()}"
@@ -325,3 +363,35 @@ class Binary(Expr):
 
     def __repr__(self):
         return f"Binary({self.op}, {self.left}, {self.right}, {self.type})"
+
+
+@typing.final
+class Index(Expr):
+    """An indexing expression.
+
+    Args:
+        target: The object being indexed.
+        index: The expression doing the indexing.
+        type: The resolved type of the result.
+    """
+
+    __slots__ = ("target", "index")
+
+    def __init__(self, target: Expr, index: Expr, type: types.Type):
+        self.target = target
+        self.index = index
+        self.type = type
+
+    def accept(self, visitor, /):
+        return visitor.visit_index(self)
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, Index)
+            and self.type == other.type
+            and self.target == other.target
+            and self.index == other.index
+        )
+
+    def __repr__(self):
+        return f"Index({self.target}, {self.index}, {self.type})"

qiskit/circuit/classical/expr/visitors.py

@@ -55,6 +55,9 @@ class ExprVisitor(typing.Generic[_T_co]):
     def visit_cast(self, node: expr.Cast, /) -> _T_co:  # pragma: no cover
         return self.visit_generic(node)
 
+    def visit_index(self, node: expr.Index, /) -> _T_co:  # pragma: no cover
+        return self.visit_generic(node)
+
 
 class _VarWalkerImpl(ExprVisitor[typing.Iterable[expr.Var]]):
     __slots__ = ()
@@ -75,6 +78,10 @@ class _VarWalkerImpl(ExprVisitor[typing.Iterable[expr.Var]]):
     def visit_cast(self, node, /):
         yield from node.operand.accept(self)
 
+    def visit_index(self, node, /):
+        yield from node.target.accept(self)
+        yield from node.index.accept(self)
+
 
 _VAR_WALKER = _VarWalkerImpl()
 
@@ -164,6 +171,16 @@ class _StructuralEquivalenceImpl(ExprVisitor[bool]):
         self.other = self.other.operand
         return node.operand.accept(self)
 
+    def visit_index(self, node, /):
+        if self.other.__class__ is not node.__class__ or self.other.type != node.type:
+            return False
+        other = self.other
+        self.other = other.target
+        if not node.target.accept(self):
+            return False
+        self.other = other.index
+        return node.index.accept(self)
+
 
 def structurally_equivalent(
     left: expr.Expr,
@@ -215,3 +232,69 @@ def structurally_equivalent(
             True
     """
     return left.accept(_StructuralEquivalenceImpl(right, left_var_key, right_var_key))
+
+
+class _IsLValueImpl(ExprVisitor[bool]):
+    __slots__ = ()
+
+    def visit_var(self, node, /):
+        return True
+
+    def visit_value(self, node, /):
+        return False
+
+    def visit_unary(self, node, /):
+        return False
+
+    def visit_binary(self, node, /):
+        return False
+
+    def visit_cast(self, node, /):
+        return False
+
+    def visit_index(self, node, /):
+        return node.target.accept(self)
+
+
+_IS_LVALUE = _IsLValueImpl()
+
+
+def is_lvalue(node: expr.Expr, /) -> bool:
+    """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
+
+        :class:`~.expr.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
+    """
+    return node.accept(_IS_LVALUE)