qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/utils/units.py

@@ -0,0 +1,146 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017.
+#
+# 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.
+
+"""SI unit utilities"""
+from __future__ import annotations
+
+import typing
+
+import numpy as np
+
+if typing.TYPE_CHECKING:
+    from qiskit.circuit.parameterexpression import ParameterExpression
+
+
+def apply_prefix(value: float | ParameterExpression, unit: str) -> float | ParameterExpression:
+    """
+    Given a SI unit prefix and value, apply the prefix to convert to
+    standard SI unit.
+
+    Args:
+        value: The number to apply prefix to.
+        unit: String prefix.
+
+    Returns:
+        Converted value.
+
+    .. note::
+
+        This may induce tiny value error due to internal representation of float object.
+        See https://docs.python.org/3/tutorial/floatingpoint.html for details.
+
+    Raises:
+        ValueError: If the ``units`` aren't recognized.
+    """
+    prefactors = {
+        "f": -15,
+        "p": -12,
+        "n": -9,
+        "u": -6,
+        "µ": -6,
+        "m": -3,
+        "k": 3,
+        "M": 6,
+        "G": 9,
+        "T": 12,
+        "P": 15,
+    }
+
+    if not unit or len(unit) == 1:
+        # for example, "m" can represent meter
+        return value
+
+    if unit[0] not in prefactors:
+        raise ValueError(f"Could not understand unit: {unit}")
+
+    pow10 = prefactors[unit[0]]
+
+    # to avoid round-off error of prefactor
+    if pow10 < 0:
+        return value / pow(10, -pow10)
+
+    return value * pow(10, pow10)
+
+
+def detach_prefix(value: float, decimal: int | None = None) -> tuple[float, str]:
+    """
+    Given a SI unit value, find the most suitable prefix to scale the value.
+
+    For example, the ``value = 1.3e8`` will be converted into a tuple of ``(130.0, "M")``,
+    which represents a scaled value and auxiliary unit that may be used to display the value.
+    In above example, that value might be displayed as ``130 MHz`` (unit is arbitrary here).
+
+    Example:
+
+        >>> value, prefix = detach_prefix(1e4)
+        >>> print(f"{value} {prefix}Hz")
+        10 kHz
+
+    Args:
+        value: The number to find prefix.
+        decimal: Optional. An arbitrary integer number to represent a precision of the value.
+            If specified, it tries to round the mantissa and adjust the prefix to rounded value.
+            For example, 999_999.91 will become 999.9999 k with ``decimal=4``,
+            while 1.0 M with ``decimal=3`` or less.
+
+    Returns:
+        A tuple of scaled value and prefix.
+
+    .. note::
+
+        This may induce tiny value error due to internal representation of float object.
+        See https://docs.python.org/3/tutorial/floatingpoint.html for details.
+
+    Raises:
+        ValueError: If the ``value`` is out of range.
+        ValueError: If the ``value`` is not real number.
+    """
+    prefactors = {
+        -15: "f",
+        -12: "p",
+        -9: "n",
+        -6: "µ",
+        -3: "m",
+        0: "",
+        3: "k",
+        6: "M",
+        9: "G",
+        12: "T",
+        15: "P",
+    }
+
+    if not np.isreal(value):
+        raise ValueError(f"Input should be real number. Cannot convert {value}.")
+
+    if np.abs(value) != 0:
+        pow10 = int(np.floor(np.log10(np.abs(value)) / 3) * 3)
+    else:
+        pow10 = 0
+
+    # to avoid round-off error of prefactor
+    if pow10 > 0:
+        mant = value / pow(10, pow10)
+    else:
+        mant = value * pow(10, -pow10)
+
+    if decimal is not None:
+        # Corner case handling
+        # For example, 999_999.99 can be rounded to 1000.0 k rather than 1.0 M.
+        mant = np.round(mant, decimal)
+        if mant >= 1000:
+            mant /= 1000
+            pow10 += 3
+
+    if pow10 not in prefactors:
+        raise ValueError(f"Value is out of range: {value}")
+
+    return mant, prefactors[pow10]

qiskit/version.py

@@ -0,0 +1,84 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2018.
+#
+# 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.
+
+# pylint: disable=no-name-in-module,broad-except,cyclic-import
+
+"""Contains Qiskit version."""
+
+import os
+import subprocess
+
+ROOT_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+def _minimal_ext_cmd(cmd):
+    # construct minimal environment
+    env = {}
+    for k in ["SYSTEMROOT", "PATH"]:
+        v = os.environ.get(k)
+        if v is not None:
+            env[k] = v
+    # LANGUAGE is used on win32
+    env["LANGUAGE"] = "C"
+    env["LANG"] = "C"
+    env["LC_ALL"] = "C"
+    with subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+        cwd=os.path.join(os.path.dirname(ROOT_DIR)),
+    ) as proc:
+        stdout, stderr = proc.communicate()
+        if proc.returncode > 0:
+            error_message = stderr.strip().decode("ascii")
+            raise OSError(f"Command {cmd} exited with code {proc.returncode}: {error_message}")
+    return stdout
+
+
+def git_version():
+    """Get the current git head sha1."""
+    # Determine if we're at main
+    try:
+        out = _minimal_ext_cmd(["git", "rev-parse", "HEAD"])
+        git_revision = out.strip().decode("ascii")
+    except OSError:
+        git_revision = "Unknown"
+
+    return git_revision
+
+
+with open(os.path.join(ROOT_DIR, "VERSION.txt")) as version_file:
+    VERSION = version_file.read().strip()
+
+
+def get_version_info():
+    """Get the full version string."""
+    # Adding the git rev number needs to be done inside
+    # write_version_py(), otherwise the import of scipy.version messes
+    # up the build under Python 3.
+    full_version = VERSION
+
+    if not os.path.exists(os.path.join(os.path.dirname(ROOT_DIR), ".git")):
+        return full_version
+    try:
+        release = _minimal_ext_cmd(["git", "tag", "-l", "--points-at", "HEAD"])
+    except Exception:  # pylint: disable=broad-except
+        return full_version
+    git_revision = git_version()
+    if not release:
+        full_version += ".dev0+" + git_revision[:7]
+
+    return full_version
+
+
+__version__ = get_version_info()

qiskit/visualization/__init__.py

@@ -0,0 +1,290 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2022.
+#
+# 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.
+
+"""
+============================================
+Visualizations (:mod:`qiskit.visualization`)
+============================================
+
+.. currentmodule:: qiskit.visualization
+
+The visualization module contain functions that visualizes measurement outcome counts, quantum
+states, circuits, devices and more.
+
+To use visualization functions, you are required to install visualization optionals to your
+development environment:
+
+.. code-block:: bash
+
+   pip install 'qiskit[visualization]'
+
+Common Keyword Arguments
+========================
+
+Many of the figures created by visualization functions in this module are created by `Matplotlib
+<https://matplotlib.org/>`_ and accept a subset of the following common arguments. Consult the
+individual documentation for exact details.
+
+* ``title`` (``str``): a text string to use for the plot title.
+* ``legend`` (``list``): a list of strings to use for labels of the data.
+* ``figsize`` (``tuple``): figure size in inches .
+* ``color`` (``list``): a list of strings for plotting.
+* ``ax`` (`matplotlib.axes.Axes <https://matplotlib.org/stable/api/axes_api.html>`_): An optional
+  ``Axes`` object to be used for the visualization output. If none is specified a new
+  `matplotlib.figure.Figure <https://matplotlib.org/stable/api/figure_api.html>`_ will be created
+  and used. Additionally, if specified there will be no returned ``Figure`` since it is redundant.
+* ``filename`` (``str``): file path to save image to.
+
+The following example demonstrates the common usage of these arguments:
+
+.. plot::
+   :alt: Output from the previous code.
+   :include-source:
+
+   from qiskit.visualization import plot_histogram
+
+   counts1 = {'00': 499, '11': 501}
+   counts2 = {'00': 511, '11': 489}
+
+   data = [counts1, counts2]
+   plot_histogram(data)
+
+You can specify ``legend``, ``title``, ``figsize`` and ``color`` by passing to the kwargs.
+
+.. plot::
+   :alt: Output from the previous code.
+   :include-source:
+   :context: reset
+
+   from qiskit.visualization import plot_histogram
+
+   counts1 = {'00': 499, '11': 501}
+   counts2 = {'00': 511, '11': 489}
+   data = [counts1, counts2]
+
+   legend = ['First execution', 'Second execution']
+   title = 'New histogram'
+   figsize = (10,10)
+   color=['crimson','midnightblue']
+   plot_histogram(data, legend=legend, title=title, figsize=figsize, color=color)
+
+You can save the figure to file either by passing the file name to ``filename`` kwarg or use
+`matplotlib.figure.Figure.savefig
+<https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure.savefig>`_ method.
+
+.. code-block:: python
+
+   plot_histogram(data, filename='new_hist.png')
+
+   hist = plot_histogram(data)
+   hist.savefig('new_hist.png')
+
+
+Counts Visualizations
+=====================
+
+This section contains functions that visualize measurement outcome counts.
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   plot_histogram
+
+Example Usage
+-------------
+
+Here is an example of using :func:`plot_histogram` to visualize measurement outcome counts:
+
+.. plot::
+   :alt: Output from the previous code.
+   :include-source:
+
+   from qiskit.visualization import plot_histogram
+
+   counts = {"00": 501, "11": 499}
+   plot_histogram(counts)
+
+The data can be a dictionary with bit string as key and counts as value, or more commonly a
+:class:`~qiskit.result.Counts` object obtained from :meth:`~qiskit.result.Result.get_counts`.
+
+Distribution Visualizations
+===========================
+
+This section contains functions that visualize sampled distributions.
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   plot_distribution
+
+State Visualizations
+====================
+
+This section contains functions that visualize quantum states.
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   plot_bloch_vector
+   plot_bloch_multivector
+   plot_state_city
+   plot_state_hinton
+   plot_state_paulivec
+   plot_state_qsphere
+
+Example Usage
+-------------
+
+Here is an example of using :func:`plot_state_city` to visualize a quantum state:
+
+.. plot::
+   :alt: Output from the previous code.
+   :include-source:
+
+   from qiskit.visualization import plot_state_city
+
+   state = [[ 0.75  , 0.433j],
+            [-0.433j, 0.25  ]]
+   plot_state_city(state)
+
+The state can be array-like list of lists, ``numpy.array``, or more commonly
+:class:`~qiskit.quantum_info.Statevector` or :class:`~qiskit.quantum_info.DensityMatrix` objects
+obtained from a :class:`~qiskit.circuit.QuantumCircuit`:
+
+.. plot::
+   :alt: Output from the previous code.
+   :include-source:
+
+   from qiskit import QuantumCircuit
+   from qiskit.quantum_info import Statevector
+   from qiskit.visualization import plot_state_city
+
+   qc = QuantumCircuit(2)
+   qc.h(0)
+   qc.cx(0,1)
+
+   # plot using a Statevector
+   state = Statevector(qc)
+   plot_state_city(state)
+
+.. plot::
+   :alt: Output from the previous code.
+   :include-source:
+
+   from qiskit import QuantumCircuit
+   from qiskit.quantum_info import DensityMatrix
+   from qiskit.visualization import plot_state_city
+
+   qc = QuantumCircuit(2)
+   qc.h(0)
+   qc.cx(0,1)
+
+   # plot using a DensityMatrix
+   state = DensityMatrix(qc)
+   plot_state_city(state)
+
+You can find code examples for each visualization functions on the individual function API page.
+
+Device Visualizations
+=====================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   plot_gate_map
+   plot_error_map
+   plot_circuit_layout
+   plot_coupling_map
+
+Circuit Visualizations
+======================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   circuit_drawer
+
+DAG Visualizations
+==================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   dag_drawer
+
+Pass Manager Visualizations
+===========================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   pass_manager_drawer
+
+Timeline Visualizations
+=======================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   timeline_drawer
+
+Single Qubit State Transition Visualizations
+============================================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   visualize_transition
+
+Array/Matrix Visualizations
+===========================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   array_to_latex
+
+Exceptions
+==========
+
+.. autoexception:: VisualizationError
+"""
+
+import os
+import sys
+
+from .array import array_to_latex
+
+from .circuit import circuit_drawer
+from .counts_visualization import plot_histogram, plot_distribution
+from .state_visualization import (
+    plot_state_hinton,
+    plot_bloch_vector,
+    plot_bloch_multivector,
+    plot_state_city,
+    plot_state_paulivec,
+    plot_state_qsphere,
+    state_drawer,
+)
+from .transition_visualization import visualize_transition
+from .dag_visualization import dag_drawer
+from .gate_map import plot_gate_map, plot_circuit_layout, plot_error_map, plot_coupling_map
+from .pass_manager_visualization import pass_manager_drawer
+from .pass_manager_visualization import staged_pass_manager_drawer
+
+from .timeline import draw as timeline_drawer
+
+from .exceptions import VisualizationError
+
+# These modules aren't part of the public interface, and were moved in Terra 0.22.  They're
+# re-imported here to allow a backwards compatible path, and should be deprecated in Terra 0.23.
+from .circuit import text, matplotlib, latex