13159304624

Committed 05 Feb 2025 02:13PM UTC coverage: 88.648% (-0.02%) from 88.667%

Build # 13159304624

Build Type

Pull #13786

github

Committed by

web-flow

Commit Message

Merge 5b9e39044 into 69bb4391b

Pull Request Pull Request #13786: Deprecate `ClassicalFunction`

Coverage Stats

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

24 existing lines in 5 files now uncovered.

78947 of 89057 relevant lines covered (88.65%)

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

.. warning::
    
    This module is deprecated as of qiskit 1.4.0 version. It will be removed in the Qiskit 2.0 release.

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

Qiskit / qiskit / 13159304624

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