13154986100

Committed 05 Feb 2025 10:10AM UTC coverage: 88.657% (-0.01%) from 88.667%

Build # 13154986100

Build Type

Pull #13786

github

Committed by

web-flow

Commit Message

Merge 19b6566ce into 69bb4391b

Pull Request Pull Request #13786: Deprecate `ClassicalFunction`

Coverage Stats

0 of 5 new or added lines in 2 files covered. (0.0%)

16 existing lines in 4 files now uncovered.

78955 of 89057 relevant lines covered (88.66%)

350858.52 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/qiskit/circuit/classicalfunction/__init__.py

# 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:: python

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

  .. code-block:: 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 qiskit.utils.deprecation import deprecate_func
from .classicalfunction import ClassicalFunction
from .exceptions import (
    ClassicalFunctionParseError,
    ClassicalFunctionCompilerError,
    ClassicalFunctionCompilerTypeError,
)
from .boolean_expression import BooleanExpression


@deprecate_func(
    since="1.4",
    removal_timeline="in Qiskit 2.0",
    additional_msg="Use `BooleanExpression` instead",
)
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__)

1	# This code is part of Qiskit.
2	#
3	# (C) Copyright IBM 2020.
4	#
5	# This code is licensed under the Apache License, Version 2.0. You may
6	# obtain a copy of this license in the LICENSE.txt file in the root directory
7	# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
8	#
9	# Any modifications or derivative works of this code must retain this
10	# copyright notice, and modified files need to carry a notice indicating
11	# that they have been altered from the originals.
12
13	"""
14	====================================================================
15	ClassicalFunction compiler (:mod:`qiskit.circuit.classicalfunction`)
16	====================================================================
17
18	.. currentmodule:: qiskit.circuit.classicalfunction
19
20	Overview
21	========
22
23	The classical function compiler provides the necessary tools to map a classical
24	potentially irreversible functions into quantum circuits. Below is a simple example of
25	how to synthesize a simple boolean function defined using Python into a
26	QuantumCircuit:
27
28	.. code-block:: python
29
30	from qiskit.circuit.classicalfunction import classical_function
31	from qiskit.circuit.classicalfunction.types import Int1
32
33	@classical_function
34	def grover_oracle(a: Int1, b: Int1, c: Int1, d: Int1) -> Int1:
35	return (not a and b and not c and d)
36
37	quantum_circuit = grover_oracle.synth(registerless=False)
38	quantum_circuit.draw('text')
39
40	.. code-block:: text
41
42	a: ──o──
43	│
44	b: ──■──
45	│
46	c: ──o──
47	│
48	d: ──■──
49	┌─┴─┐
50	return: ┤ X ├
51	└───┘
52
53	Following Qiskit's little-endian bit ordering convention, the left-most bit (``a``) is the most
54	significant bit and the right-most bit (``d``) is the least significant bit.
55
56	.. warning::
57
58	The functionality of `qiskit.circuit.classicalfunction` requires `tweedledum`,
59	which isn't available on all platforms (up to Python version 3.11).
60	See `tweedledum installation guide
61	<https://github.com/boschmitt/tweedledum/tree/master?tab=readme-ov-file#installation>`_
62	for more details.
63
64	Supplementary Information
65	=========================
66
67	Tweedledum
68	----------
69
70	Tweedledum is a C++-17 header-only library that implements a large set of
71	reversible (and quantum) synthesis, optimization, and mapping algorithms.
72	The classical function compiler relies on it and its dependencies to both represent logic
73	networks and synthesize them into quantum circuits.
74
75	ClassicalFunction data types
76	----------------------------
77
78	At the moment, the only type supported by the classical_function compilers is
79	``qiskit.circuit.classicalfunction.types.Int1``. The classical function function
80	to parse must include type hints (just ``Int1`` for now). The resulting gate
81	will be a gate in the size of the sum of all the parameters and the return.
82
83	The type ``Int1`` means the classical function will only operate at bit level.
84
85
86	ClassicalFunction compiler API
87	==============================
88
89	classical_function
90	------------------
91
92	Decorator for a classical function that returns a `ClassicalFunction` object.
93
94	.. autofunction:: classical_function
95
96	ClassicalFunction
97	-----------------
98
99	.. autosummary::
100	:toctree: ../stubs/
101
102	ClassicalFunction
103	BooleanExpression
104
105	Exceptions
106	----------
107
108	.. autosummary::
109	:toctree: ../stubs/
110
111	ClassicalFunctionCompilerTypeError
112	ClassicalFunctionParseError
113	ClassicalFunctionCompilerTypeError
114
115	"""
NEW 116	from qiskit.utils.deprecation import deprecate_func	×
117	from .classicalfunction import ClassicalFunction	×
118	from .exceptions import (	×
119	ClassicalFunctionParseError,
120	ClassicalFunctionCompilerError,
121	ClassicalFunctionCompilerTypeError,
122	)
123	from .boolean_expression import BooleanExpression	×
124
125
NEW 126	@deprecate_func(	×
127	since="1.4",
128	removal_timeline="in Qiskit 2.0",
129	additional_msg="Use `BooleanExpression` instead",
130	)
UNCOV 131	def classical_function(func):	×
132	"""
133	Parses and type checks the callable ``func`` to compile it into an ``ClassicalFunction``
134	that can be synthesized into a ``QuantumCircuit``.
135
136	Args:
137	func (callable): A callable (with type hints) to compile into an ``ClassicalFunction``.
138
139	Returns:
140	ClassicalFunction: An object that can synthesis into a QuantumCircuit (via ``synth()``
141	method).
142	"""
143	import inspect	×
144	from textwrap import dedent	×
145
146	source = dedent(inspect.getsource(func))	×
147	return ClassicalFunction(source, name=func.__name__)	×

Qiskit / qiskit / 13154986100

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous