qiskit 1.3.0__cp39-abi3-macosx_11_0_arm64.whl

qiskit/circuit/classical/types/__init__.py

@@ -0,0 +1,109 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+==============================================
+Typing (:mod:`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 :mod:`~.classical.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:
+
+.. autoclass:: Type
+
+Types should be considered immutable objects, and you must not mutate them.  It is permissible to
+reuse a :class:`Type` that you take from another object without copying it, and generally this will
+be the best approach for performance.  :class:`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 :class:`.Clbit` and the
+literals ``True`` and ``False``), and unsigned integers (corresponding to
+:class:`.ClassicalRegister` and Python integers).
+
+.. autoclass:: Bool
+.. autoclass:: Uint
+
+Note that :class:`Uint` defines a family of types parametrized 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 additional functions on these types documented in the subsequent sections. 
+These are mostly expected to be used only in manipulations of the expression tree;
+users who are building expressions using the
+:ref:`user-facing construction interface <circuit-classical-expressions-expr-construction>` should
+not need to use these.
+
+Partial ordering of types
+=========================
+
+The type system is equipped with a partial ordering, where :math:`a < b` is interpreted as
+":math:`a` is a strict subtype of :math:`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 :func:`order` function.
+
+.. autofunction:: order
+
+The return value is an enumeration :class:`Ordering` that describes what, if any, subtyping
+relationship exists between the two types.
+
+.. autoclass:: Ordering
+    :member-order: bysource
+
+Some helper methods are then defined in terms of this low-level :func:`order` primitive:
+
+.. autofunction:: is_subtype
+.. autofunction:: is_supertype
+.. autofunction:: greater
+
+
+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 :mod:`types` module.  You can query the casting kinds using :func:`cast_kind`:
+
+.. autofunction:: cast_kind
+
+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.
+
+.. autoclass:: CastKind
+"""
+
+__all__ = [
+    "Type",
+    "Bool",
+    "Uint",
+    "Ordering",
+    "order",
+    "is_subtype",
+    "is_supertype",
+    "greater",
+    "CastKind",
+    "cast_kind",
+]
+
+from .types import Type, Bool, Uint
+from .ordering import Ordering, order, is_subtype, is_supertype, greater, CastKind, cast_kind

qiskit/circuit/classical/types/ordering.py

@@ -0,0 +1,222 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Tools for working with the partial ordering of the type system."""
+
+from __future__ import annotations
+
+__all__ = [
+    "Ordering",
+    "is_subtype",
+    "is_supertype",
+    "order",
+    "greater",
+    "CastKind",
+    "cast_kind",
+]
+
+import enum
+
+from .types import Type, Bool, Uint
+
+
+# While the type system is simple, it's overkill to represent the complete partial ordering graph of
+# the set of types in an explicit graph form.  The strategy here is to assume that two types have no
+# ordering between them, and an ordering is defined by putting a function `Type * Type -> Ordering`
+# into the `_ORDERERS`.
+
+
+class Ordering(enum.Enum):
+    """Enumeration listing the possible relations between two types.  Types only have a partial
+    ordering, so it's possible for two types to have no sub-typing relationship.
+
+    Note that the sub-/supertyping relationship is not the same as whether a type can be explicitly
+    cast from one to another."""
+
+    LESS = enum.auto()
+    """The left type is a strict subtype of the right type."""
+    EQUAL = enum.auto()
+    """The two types are equal."""
+    GREATER = enum.auto()
+    """The left type is a strict supertype of the right type."""
+    NONE = enum.auto()
+    """There is no typing relationship between the two types."""
+
+    def __repr__(self):
+        return str(self)
+
+
+def _order_bool_bool(_a: Bool, _b: Bool, /) -> Ordering:
+    return Ordering.EQUAL
+
+
+def _order_uint_uint(left: Uint, right: Uint, /) -> Ordering:
+    if left.width < right.width:
+        return Ordering.LESS
+    if left.width == right.width:
+        return Ordering.EQUAL
+    return Ordering.GREATER
+
+
+_ORDERERS = {
+    (Bool, Bool): _order_bool_bool,
+    (Uint, Uint): _order_uint_uint,
+}
+
+
+def order(left: Type, right: Type, /) -> Ordering:
+    """Get the ordering relationship between the two types as an enumeration value.
+
+    Examples:
+        Compare two :class:`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
+    """
+    if (orderer := _ORDERERS.get((left.kind, right.kind))) is None:
+        return Ordering.NONE
+    return orderer(left, right)
+
+
+def is_subtype(left: Type, right: Type, /, strict: bool = False) -> bool:
+    r"""Does the relation :math:`\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
+    """
+    order_ = order(left, right)
+    return order_ is Ordering.LESS or (not strict and order_ is Ordering.EQUAL)
+
+
+def is_supertype(left: Type, right: Type, /, strict: bool = False) -> bool:
+    r"""Does the relation :math:`\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
+    """
+    order_ = order(left, right)
+    return order_ is Ordering.GREATER or (not strict and order_ is Ordering.EQUAL)
+
+
+def greater(left: Type, right: Type, /) -> Type:
+    """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.
+
+    Examples:
+        Find the greater of two :class:`Uint` types::
+
+            >>> from qiskit.circuit.classical import types
+            >>> types.greater(types.Uint(8), types.Uint(16))
+            types.Uint(16)
+    """
+    order_ = order(left, right)
+    if order_ is Ordering.NONE:
+        raise TypeError(f"no ordering exists between '{left}' and '{right}'")
+    return left if order_ is Ordering.GREATER else right
+
+
+class CastKind(enum.Enum):
+    """A return value indicating the type of cast that can occur from one type to another."""
+
+    EQUAL = enum.auto()
+    """The two types are equal; no cast node is required at all."""
+    IMPLICIT = enum.auto()
+    """The 'from' type can be cast to the 'to' type implicitly.  A :class:`~.expr.Cast` node with
+    ``implicit==True`` is the minimum required to specify this."""
+    LOSSLESS = enum.auto()
+    """The 'from' type can be cast to the 'to' type explicitly, and the cast will be lossless.  This
+    requires a :class:`~.expr.Cast`` node with ``implicit=False``, but there's no danger from
+    inserting one."""
+    DANGEROUS = enum.auto()
+    """The 'from' type has a defined cast to the 'to' type, but depending on the value, it may lose
+    data.  A user would need to manually specify casts."""
+    NONE = enum.auto()
+    """There is no casting permitted from the 'from' type to the 'to' type."""
+
+
+def _uint_cast(from_: Uint, to_: Uint, /) -> CastKind:
+    if from_.width == to_.width:
+        return CastKind.EQUAL
+    if from_.width < to_.width:
+        return CastKind.LOSSLESS
+    return CastKind.DANGEROUS
+
+
+_ALLOWED_CASTS = {
+    (Bool, Bool): lambda _a, _b, /: CastKind.EQUAL,
+    (Bool, Uint): lambda _a, _b, /: CastKind.LOSSLESS,
+    (Uint, Bool): lambda _a, _b, /: CastKind.IMPLICIT,
+    (Uint, Uint): _uint_cast,
+}
+
+
+def cast_kind(from_: Type, to_: Type, /) -> CastKind:
+    """Determine the sort of cast that is required to move from the left type to the right type.
+
+    Examples:
+
+        .. code-block:: python
+
+            >>> 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>
+    """
+    if (coercer := _ALLOWED_CASTS.get((from_.kind, to_.kind))) is None:
+        return CastKind.NONE
+    return coercer(from_, to_)

qiskit/circuit/classical/types/types.py

@@ -0,0 +1,117 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Type-system definition for the expression tree."""
+
+# Given the nature of the tree representation and that there are helper functions associated with
+# many of the classes whose arguments naturally share names with themselves, it's inconvenient to
+# use synonyms everywhere.  This goes for the builtin 'type' as well.
+# pylint: disable=redefined-builtin,redefined-outer-name
+
+from __future__ import annotations
+
+__all__ = [
+    "Type",
+    "Bool",
+    "Uint",
+]
+
+import typing
+
+
+class _Singleton(type):
+    """Metaclass to make the child, which should take zero initialization arguments, a singleton
+    object."""
+
+    def _get_singleton_instance(cls):
+        return cls._INSTANCE
+
+    @classmethod
+    def __prepare__(mcs, name, bases):  # pylint: disable=unused-argument
+        return {"__new__": mcs._get_singleton_instance}
+
+    @staticmethod
+    def __new__(cls, name, bases, namespace):
+        out = super().__new__(cls, name, bases, namespace)
+        out._INSTANCE = object.__new__(out)  # pylint: disable=invalid-name
+        return out
+
+
+class Type:
+    """Root base class of all nodes in the type tree.  The base case should never be instantiated
+    directly.
+
+    This must not be subclassed by users; subclasses form the internal data of the representation of
+    expressions, and it does not make sense to add more outside of Qiskit library code."""
+
+    __slots__ = ()
+
+    @property
+    def kind(self):
+        """Get the kind of this type.  This is exactly equal to the Python type object that defines
+        this type, that is ``t.kind is type(t)``, but is exposed like this to make it clear that
+        this a hashable enum-like discriminator you can rely on."""
+        return self.__class__
+
+    # Enforcement of immutability.  The constructor methods need to manually skip this.
+
+    def __setattr__(self, _key, _value):
+        raise AttributeError(f"'{self.kind.__name__}' instances are immutable")
+
+    def __copy__(self):
+        return self
+
+    def __deepcopy__(self, _memo):
+        return self
+
+    def __setstate__(self, state):
+        _dict, slots = state
+        for slot, value in slots.items():
+            # We need to overcome the type's enforcement of immutability post initialization.
+            super().__setattr__(slot, value)
+
+
+@typing.final
+class Bool(Type, metaclass=_Singleton):
+    """The Boolean type.  This has exactly two values: ``True`` and ``False``."""
+
+    __slots__ = ()
+
+    def __repr__(self):
+        return "Bool()"
+
+    def __hash__(self):
+        return hash(self.__class__)
+
+    def __eq__(self, other):
+        return isinstance(other, Bool)
+
+
+@typing.final
+class Uint(Type):
+    """An unsigned integer of fixed bit width."""
+
+    __slots__ = ("width",)
+
+    def __init__(self, width: int):
+        if isinstance(width, int) and width <= 0:
+            raise ValueError("uint width must be greater than zero")
+        super(Type, self).__setattr__("width", width)
+
+    def __repr__(self):
+        return f"Uint({self.width})"
+
+    def __hash__(self):
+        return hash((self.__class__, self.width))
+
+    def __eq__(self, other):
+        return isinstance(other, Uint) and self.width == other.width

qiskit/circuit/classicalfunction/__init__.py

@@ -0,0 +1,140 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+====================================================================
+ClassicalFunction compiler (:mod:`qiskit.circuit.classicalfunction`)
+====================================================================
+
+.. currentmodule:: qiskit.circuit.classicalfunction
+
+Overview
+========
+
+The classical function compiler provides the necessary tools to map a classical
+potentially irreversible functions into quantum circuits.  Below is a simple example of
+how to synthesize a simple boolean function defined using Python into a
+QuantumCircuit:
+
+   .. code-block::
+
+      from qiskit.circuit.classicalfunction import classical_function
+      from qiskit.circuit.classicalfunction.types import Int1
+
+      @classical_function
+      def grover_oracle(a: Int1, b: Int1, c: Int1, d: Int1) -> Int1:
+          return (not a and b and not c and d)
+
+      quantum_circuit = grover_oracle.synth(registerless=False)
+      quantum_circuit.draw('text')
+
+           a: ──o──
+                │
+           b: ──■──
+                │
+           c: ──o──
+                │
+           d: ──■──
+              ┌─┴─┐
+      return: ┤ X ├
+              └───┘
+
+Following Qiskit's little-endian bit ordering convention, the left-most bit (``a``) is the most
+significant bit and the right-most bit (``d``) is the least significant bit.
+
+.. warning::
+
+    The functionality of `qiskit.circuit.classicalfunction` requires `tweedledum`, 
+    which isn't available on all platforms (up to Python version 3.11).
+    See `tweedledum installation guide 
+    <https://github.com/boschmitt/tweedledum/tree/master?tab=readme-ov-file#installation>`_ 
+    for more details.
+
+Supplementary Information
+=========================
+
+Tweedledum
+----------
+
+Tweedledum is a C++-17 header-only library that implements a large set of
+reversible (and quantum) synthesis, optimization, and mapping algorithms.
+The classical function compiler relies on it and its dependencies to both represent logic
+networks and synthesize them into quantum circuits.
+
+ClassicalFunction data types
+----------------------------
+
+At the moment, the only type supported by the classical_function compilers is
+``qiskit.circuit.classicalfunction.types.Int1``. The classical function function
+to parse *must* include type hints (just ``Int1`` for now). The resulting gate
+will be a gate in the size of the sum of all the parameters and the return.
+
+The type ``Int1`` means the classical function will only operate at bit level.
+
+
+ClassicalFunction compiler API
+==============================
+
+classical_function
+------------------
+
+Decorator for a classical function that returns a `ClassicalFunction` object.
+
+.. autofunction:: classical_function
+
+ClassicalFunction
+-----------------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   ClassicalFunction
+   BooleanExpression
+
+Exceptions
+----------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   ClassicalFunctionCompilerTypeError
+   ClassicalFunctionParseError
+   ClassicalFunctionCompilerTypeError
+
+"""
+
+from .classicalfunction import ClassicalFunction
+from .exceptions import (
+    ClassicalFunctionParseError,
+    ClassicalFunctionCompilerError,
+    ClassicalFunctionCompilerTypeError,
+)
+from .boolean_expression import BooleanExpression
+
+
+def classical_function(func):
+    """
+    Parses and type checks the callable ``func`` to compile it into an ``ClassicalFunction``
+    that can be synthesized into a ``QuantumCircuit``.
+
+    Args:
+        func (callable): A callable (with type hints) to compile into an ``ClassicalFunction``.
+
+    Returns:
+        ClassicalFunction: An object that can synthesis into a QuantumCircuit (via ``synth()``
+        method).
+    """
+    import inspect
+    from textwrap import dedent
+
+    source = dedent(inspect.getsource(func))
+    return ClassicalFunction(source, name=func.__name__)