qiskit 1.3.0__cp39-abi3-macosx_11_0_arm64.whl

qiskit/utils/optionals.py

@@ -0,0 +1,347 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 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.
+
+"""
+.. currentmodule:: qiskit.utils.optionals
+
+Qiskit has several features that are enabled only if certain *optional* dependencies
+are satisfied. This module, :mod:`qiskit.utils.optionals`, has a collection of objects that can
+be used to test if certain functionality is available, and optionally raise
+:class:`.MissingOptionalLibraryError` if the functionality is not available.
+
+
+Available Testers
+=================
+
+Qiskit Components
+-----------------
+
+.. py:data:: HAS_AER
+
+    `Qiskit Aer <https://qiskit.github.io/qiskit-aer/>` provides high-performance simulators for
+    the quantum circuits constructed within Qiskit.
+
+.. py:data:: HAS_IBMQ
+
+    The :mod:`Qiskit IBMQ Provider <qiskit.providers.ibmq>` is used for accessing IBM Quantum
+    hardware in the IBM cloud.
+
+.. py:data:: HAS_IGNIS
+
+    :mod:`Qiskit Ignis <qiskit.ignis>` provides tools for quantum hardware verification, noise
+    characterization, and error correction.
+
+.. py:data:: HAS_TOQM
+
+    `Qiskit TOQM <https://github.com/qiskit-toqm/qiskit-toqm>`__ provides transpiler passes
+    for the `Time-optimal Qubit mapping algorithm <https://doi.org/10.1145/3445814.3446706>`__.
+
+
+External Python Libraries
+-------------------------
+
+.. py:data:: HAS_CONSTRAINT
+
+    `python-constraint <https://github.com/python-constraint/python-constraint>`__ is a
+    constraint satisfaction problem solver, used in the :class:`~.CSPLayout` transpiler pass.
+
+.. py:data:: HAS_CPLEX
+
+    The `IBM CPLEX Optimizer <https://www.ibm.com/analytics/cplex-optimizer>`__ is a
+    high-performance mathematical programming solver for linear, mixed-integer and quadratic
+    programming. This is no longer by Qiskit, but it weas historically and the optional
+    remains for backwards compatibility.
+
+.. py:data:: HAS_CVXPY
+
+    `CVXPY <https://www.cvxpy.org/>`__ is a Python package for solving convex optimization
+    problems.  It is required for calculating diamond norms with
+    :func:`.quantum_info.diamond_norm`.
+
+.. py:data:: HAS_DOCPLEX
+
+    `IBM Decision Optimization CPLEX Modelling
+    <http://ibmdecisionoptimization.github.io/docplex-doc/>`__ is a library for prescriptive
+    analysis.  Like CPLEX, this is no longer by Qiskit, but it weas historically and the
+    optional remains for backwards compatibility.
+
+.. py:data:: HAS_FIXTURES
+
+    The test suite has additional features that are available if the optional `fixtures
+    <https://launchpad.net/python-fixtures>`__ module is installed.  This generally also needs
+    :data:`HAS_TESTTOOLS` as well.  This is generally only needed for Qiskit developers.
+
+.. py:data:: HAS_IPYTHON
+
+    If `the IPython kernel <https://ipython.org/>`__ is available, certain additional
+    visualizations and line magics are made available.
+
+.. py:data:: HAS_IPYWIDGETS
+
+    Monitoring widgets for jobs running on external backends can be provided if `ipywidgets
+    <https://ipywidgets.readthedocs.io/en/latest/>`__ is available.
+
+.. py:data:: HAS_JAX
+
+    Some methods of gradient calculation within :mod:`.opflow.gradients` require `JAX
+    <https://github.com/google/jax>`__ for autodifferentiation.
+
+.. py:data:: HAS_JUPYTER
+
+    Some of the tests require a complete `Jupyter <https://jupyter.org/>`__ installation to test
+    interactivity features.
+
+.. py:data:: HAS_MATPLOTLIB
+
+    Qiskit provides several visualization tools in the :mod:`.visualization` module.
+    Almost all of these are built using `Matplotlib <https://matplotlib.org/>`__, which must
+    be installed in order to use them.
+
+.. py:data:: HAS_NETWORKX
+
+    No longer used by Qiskit.  Internally, Qiskit now uses the high-performance `rustworkx
+    <https://github.com/Qiskit/rustworkx>`__ library as a core dependency, and during the
+    change-over period, it was sometimes convenient to convert things into the Python-only
+    `NetworkX <https://networkx.org/>`__ format.  Some tests of application modules, such as
+    `Qiskit Nature <https://qiskit-community.github.io/qiskit-nature/>`__ still use NetworkX.
+
+.. py:data:: HAS_NLOPT
+
+    `NLopt <https://nlopt.readthedocs.io/en/latest/>`__ is a nonlinear optimization library,
+    used by the global optimizers in the :mod:`.algorithms.optimizers` module.
+
+.. py:data:: HAS_PIL
+
+    PIL is a Python image-manipulation library.  Qiskit actually uses the `pillow
+    <https://pillow.readthedocs.io/en/stable/>`__ fork of PIL if it is available when generating
+    certain visualizations, for example of both :class:`.QuantumCircuit` and
+    :class:`.DAGCircuit` in certain modes.
+
+.. py:data:: HAS_PYDOT
+
+    For some graph visualizations, Qiskit uses `pydot <https://github.com/pydot/pydot>`__ as an
+    interface to GraphViz (see :data:`HAS_GRAPHVIZ`).
+
+.. py:data:: HAS_PYGMENTS
+
+    Pygments is a code highlighter and formatter used by many environments that involve rich
+    display of code blocks, including Sphinx and Jupyter.  Qiskit uses this when producing rich
+    output for these environments.
+
+.. py:data:: HAS_PYLATEX
+
+    Various LaTeX-based visualizations, especially the circuit drawers, need access to the
+    `pylatexenc <https://github.com/phfaist/pylatexenc>`__ project to work correctly.
+
+.. py:data:: HAS_QASM3_IMPORT
+
+    The functions :func:`.qasm3.load` and :func:`.qasm3.loads` for importing OpenQASM 3 programs
+    into :class:`.QuantumCircuit` instances use `an external importer package
+    <https://qiskit.github.io/qiskit-qasm3-import>`__.
+
+.. py:data:: HAS_SEABORN
+
+    Qiskit provides several visualization tools in the :mod:`.visualization` module.  Some
+    of these are built using `Seaborn <https://seaborn.pydata.org/>`__, which must be installed
+    in order to use them.
+
+.. py:data:: HAS_SKLEARN
+
+    Some of the gradient functions in :mod:`.opflow.gradients` use regularisation methods from
+    `Scikit Learn <https://scikit-learn.org/stable/>`__.
+
+.. py:data:: HAS_SKQUANT
+
+    Some of the optimisers in :mod:`.algorithms.optimizers` are based on those found in `Scikit
+    Quant <https://github.com/scikit-quant/scikit-quant>`__, which must be installed to use
+    them.
+
+.. py:data:: HAS_SQSNOBFIT
+
+    `SQSnobFit <https://pypi.org/project/SQSnobFit/>`__ is a library for the "stable noisy
+    optimization by branch and fit" algorithm.  It is used by the :class:`.SNOBFIT` optimizer.
+
+.. py:data:: HAS_SYMENGINE
+
+    `Symengine <https://github.com/symengine/symengine>`__ is a fast C++ backend for the
+    symbolic-manipulation library `Sympy <https://www.sympy.org/en/index.html>`__.  Qiskit uses
+    special methods from Symengine to accelerate its handling of
+    :class:`~.circuit.Parameter`\\ s if available.
+
+.. py:data:: HAS_TESTTOOLS
+
+    Qiskit's test suite has more advanced functionality available if the optional
+    `testtools <https://pypi.org/project/testtools/>`__ library is installed.  This is generally
+    only needed for Qiskit developers.
+
+.. py:data:: HAS_TWEEDLEDUM
+
+    `Tweedledum <https://github.com/boschmitt/tweedledum>`__ is an extension library for
+    synthesis and optimization of circuits that may involve classical oracles.  Qiskit's
+    :class:`.PhaseOracle` uses this, which is used in turn by amplification algorithms via
+    the :class:`.AmplificationProblem`.
+
+.. py:data:: HAS_Z3
+
+    `Z3 <https://github.com/Z3Prover/z3>`__ is a theorem prover, used in the
+    :class:`.CrosstalkAdaptiveSchedule` and :class:`.HoareOptimizer` transpiler passes.
+
+External Command-Line Tools
+---------------------------
+
+.. py:data:: HAS_GRAPHVIZ
+
+    For some graph visualizations, Qiskit uses the `GraphViz <https://graphviz.org/>`__
+    visualization tool via its ``pydot`` interface (see :data:`HAS_PYDOT`).
+
+.. py:data:: HAS_PDFLATEX
+
+    Visualization tools that use LaTeX in their output, such as the circuit drawers, require
+    ``pdflatex`` to be available.  You will generally need to ensure that you have a working
+    LaTeX installation available, and the ``qcircuit.tex`` package.
+
+.. py:data:: HAS_PDFTOCAIRO
+
+    Visualization tools that convert LaTeX-generated files into rasterized images use the
+    ``pdftocairo`` tool.  This is part of the `Poppler suite of PDF tools
+    <https://poppler.freedesktop.org/>`__.
+
+
+Lazy Checker Classes
+====================
+
+.. currentmodule:: qiskit.utils
+
+Each of the lazy checkers is an instance of :class:`.LazyDependencyManager` in one of its two
+subclasses: :class:`.LazyImportTester` and :class:`.LazySubprocessTester`.  These should be imported
+from :mod:`.utils` directly if required, such as::
+
+    from qiskit.utils import LazyImportTester
+
+.. autoclass:: qiskit.utils.LazyDependencyManager
+    :members:
+
+.. autoclass:: qiskit.utils.LazyImportTester
+.. autoclass:: qiskit.utils.LazySubprocessTester
+"""
+
+# NOTE: If you're changing this file, sync it with `requirements-optional.txt` and potentially
+# `pyproject.toml` as well.
+
+import logging as _logging
+
+from .lazy_tester import (
+    LazyImportTester as _LazyImportTester,
+    LazySubprocessTester as _LazySubprocessTester,
+)
+
+_logger = _logging.getLogger(__name__)
+
+HAS_AER = _LazyImportTester(
+    "qiskit_aer",
+    name="Qiskit Aer",
+    install="pip install qiskit-aer",
+)
+HAS_IBMQ = _LazyImportTester(
+    "qiskit.providers.ibmq",
+    name="IBMQ Provider",
+    install="pip install qiskit-ibmq-provider",
+)
+HAS_IGNIS = _LazyImportTester(
+    "qiskit.ignis",
+    name="Qiskit Ignis",
+    install="pip install qiskit-ignis",
+)
+HAS_TOQM = _LazyImportTester("qiskit_toqm", name="Qiskit TOQM", install="pip install qiskit-toqm")
+
+HAS_CONSTRAINT = _LazyImportTester(
+    "constraint",
+    name="python-constraint",
+    install="pip install python-constraint",
+)
+
+HAS_CPLEX = _LazyImportTester(
+    "cplex",
+    install="pip install cplex",
+    msg="This may not be possible for all Python versions and OSes",
+)
+HAS_CVXPY = _LazyImportTester("cvxpy", install="pip install cvxpy")
+HAS_DOCPLEX = _LazyImportTester(
+    {"docplex": (), "docplex.mp.model": ("Model",)},
+    install="pip install docplex",
+    msg="This may not be possible for all Python versions and OSes",
+)
+HAS_FIXTURES = _LazyImportTester("fixtures", install="pip install fixtures")
+HAS_IPYTHON = _LazyImportTester("IPython", install="pip install ipython")
+HAS_IPYWIDGETS = _LazyImportTester("ipywidgets", install="pip install ipywidgets")
+HAS_JAX = _LazyImportTester(
+    {"jax": ("grad", "jit"), "jax.numpy": ()},
+    name="jax",
+    install="pip install jax",
+)
+HAS_JUPYTER = _LazyImportTester(["jupyter", "nbformat", "nbconvert"], install="pip install jupyter")
+HAS_MATPLOTLIB = _LazyImportTester(
+    ("matplotlib.patches", "matplotlib.pyplot"),
+    name="matplotlib",
+    install="pip install matplotlib",
+)
+HAS_NETWORKX = _LazyImportTester("networkx", install="pip install networkx")
+
+HAS_NLOPT = _LazyImportTester("nlopt", name="NLopt Optimizer", install="pip install nlopt")
+HAS_PIL = _LazyImportTester("PIL.Image", name="pillow", install="pip install pillow")
+HAS_PYDOT = _LazyImportTester("pydot", install="pip install pydot")
+HAS_PYGMENTS = _LazyImportTester("pygments", install="pip install pygments")
+HAS_PYLATEX = _LazyImportTester(
+    {
+        "pylatexenc.latex2text": ("LatexNodes2Text",),
+        "pylatexenc.latexencode": ("utf8tolatex",),
+    },
+    name="pylatexenc",
+    install="pip install pylatexenc",
+)
+HAS_QASM3_IMPORT = _LazyImportTester(
+    "qiskit_qasm3_import", install="pip install qiskit_qasm3_import"
+)
+HAS_SEABORN = _LazyImportTester("seaborn", install="pip install seaborn")
+HAS_SKLEARN = _LazyImportTester(
+    {"sklearn.linear_model": ("Ridge", "Lasso")},
+    name="scikit-learn",
+    install="pip install scikit-learn",
+)
+HAS_SKQUANT = _LazyImportTester(
+    "skquant.opt",
+    name="scikit-quant",
+    install="pip install scikit-quant",
+)
+HAS_SQSNOBFIT = _LazyImportTester("SQSnobFit", install="pip install SQSnobFit")
+HAS_SYMENGINE = _LazyImportTester("symengine", install="pip install symengine")
+HAS_TESTTOOLS = _LazyImportTester("testtools", install="pip install testtools")
+HAS_TWEEDLEDUM = _LazyImportTester("tweedledum", install="pip install tweedledum")
+HAS_Z3 = _LazyImportTester("z3", install="pip install z3-solver")
+
+HAS_GRAPHVIZ = _LazySubprocessTester(
+    ("dot", "-V"),
+    name="Graphviz",
+    msg=(
+        "To install, follow the instructions at https://graphviz.org/download/."
+        " Qiskit needs the Graphviz binaries, which the 'graphviz' package on pip does not install."
+        " You must install the actual Graphviz software"
+    ),
+)
+HAS_PDFLATEX = _LazySubprocessTester(
+    ("pdflatex", "-version"),
+    msg="You will likely need to install a full LaTeX distribution for your system",
+)
+HAS_PDFTOCAIRO = _LazySubprocessTester(
+    ("pdftocairo", "-v"),
+    msg="This is part of the 'poppler' set of PDF utilities",
+)

qiskit/utils/parallel.py

@@ -0,0 +1,191 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2024.
+#
+# 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.
+
+# This file is part of QuTiP: Quantum Toolbox in Python.
+#
+#    Copyright (c) 2011 and later, Paul D. Nation and Robert J. Johansson.
+#    All rights reserved.
+#
+#    Redistribution and use in source and binary forms, with or without
+#    modification, are permitted provided that the following conditions are
+#    met:
+#
+#    1. Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+#
+#    2. Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#
+#    3. Neither the name of the QuTiP: Quantum Toolbox in Python nor the names
+#       of its contributors may be used to endorse or promote products derived
+#       from this software without specific prior written permission.
+#
+#    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+#    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+#    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+#    PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+#    HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+#    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+#    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+#    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+#    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+#    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+#    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+###############################################################################
+
+"""
+Routines for running Python functions in parallel using process pools
+from the multiprocessing library.
+"""
+
+from __future__ import annotations
+
+import os
+from concurrent.futures import ProcessPoolExecutor
+import sys
+
+from qiskit.exceptions import QiskitError
+from qiskit.utils.multiprocessing import local_hardware_info
+from qiskit import user_config
+
+
+def get_platform_parallel_default():
+    """
+    Returns the default parallelism flag value for the current platform.
+
+    Returns:
+        parallel_default: The default parallelism flag value for the
+        current platform.
+
+    """
+    # Default False on Windows
+    if sys.platform == "win32":
+        parallel_default = False
+    # On macOS default false on Python >=3.8
+    elif sys.platform == "darwin":
+        parallel_default = False
+    # On linux (and other OSes) default to True
+    else:
+        parallel_default = True
+
+    return parallel_default
+
+
+CONFIG = user_config.get_config()
+
+if os.getenv("QISKIT_PARALLEL", None) is not None:
+    PARALLEL_DEFAULT = os.getenv("QISKIT_PARALLEL", None).lower() == "true"
+else:
+    PARALLEL_DEFAULT = get_platform_parallel_default()
+
+# Set parallel flag
+if os.getenv("QISKIT_IN_PARALLEL") is None:
+    os.environ["QISKIT_IN_PARALLEL"] = "FALSE"
+
+if os.getenv("QISKIT_NUM_PROCS") is not None:
+    CPU_COUNT = int(os.getenv("QISKIT_NUM_PROCS"))
+else:
+    CPU_COUNT = CONFIG.get("num_process", local_hardware_info()["cpus"])
+
+
+def _task_wrapper(param):
+    (task, value, task_args, task_kwargs) = param
+    return task(value, *task_args, **task_kwargs)
+
+
+def should_run_in_parallel(num_processes: int | None = None) -> bool:
+    """Return whether the current parallelisation configuration suggests that we should run things
+    like :func:`parallel_map` in parallel (``True``) or degrade to serial (``False``).
+
+    Args:
+        num_processes: the number of processes requested for use (if given).
+    """
+    num_processes = CPU_COUNT if num_processes is None else num_processes
+    return (
+        num_processes > 1
+        and os.getenv("QISKIT_IN_PARALLEL", "FALSE") == "FALSE"
+        and CONFIG.get("parallel_enabled", PARALLEL_DEFAULT)
+    )
+
+
+def parallel_map(  # pylint: disable=dangerous-default-value
+    task, values, task_args=(), task_kwargs={}, num_processes=CPU_COUNT
+):
+    """
+    Parallel execution of a mapping of `values` to the function `task`. This
+    is functionally equivalent to::
+
+        result = [task(value, *task_args, **task_kwargs) for value in values]
+
+    This will parallelise the results if the number of ``values`` is greater than one, and the
+    current system configuration permits parallelization.
+
+    Args:
+        task (func): Function that is to be called for each value in ``values``.
+        values (array_like): List or array of values for which the ``task`` function is to be
+            evaluated.
+        task_args (list): Optional additional arguments to the ``task`` function.
+        task_kwargs (dict): Optional additional keyword argument to the ``task`` function.
+        num_processes (int): Number of processes to spawn.
+
+    Returns:
+        result: The result list contains the value of ``task(value, *task_args, **task_kwargs)`` for
+        each value in ``values``.
+
+    Raises:
+        QiskitError: If user interrupts via keyboard.
+
+    Examples:
+
+        .. code-block:: python
+
+            import time
+            from qiskit.utils import parallel_map
+            def func(_):
+                    time.sleep(0.1)
+                    return 0
+            parallel_map(func, list(range(10)));
+    """
+    if num_processes is None:
+        num_processes = CPU_COUNT
+    if len(values) == 0:
+        return []
+    if len(values) == 1:
+        return [task(values[0], *task_args, **task_kwargs)]
+
+    if should_run_in_parallel(num_processes):
+        os.environ["QISKIT_IN_PARALLEL"] = "TRUE"
+        try:
+            results = []
+            with ProcessPoolExecutor(max_workers=num_processes) as executor:
+                param = ((task, value, task_args, task_kwargs) for value in values)
+                future = executor.map(_task_wrapper, param)
+
+            results = list(future)
+
+        except (KeyboardInterrupt, Exception) as error:
+            if isinstance(error, KeyboardInterrupt):
+                os.environ["QISKIT_IN_PARALLEL"] = "FALSE"
+                raise QiskitError("Keyboard interrupt in parallel_map.") from error
+            # Otherwise just reset parallel flag and error
+            os.environ["QISKIT_IN_PARALLEL"] = "FALSE"
+            raise error
+
+        os.environ["QISKIT_IN_PARALLEL"] = "FALSE"
+        return results
+
+    results = []
+    for _, value in enumerate(values):
+        result = task(value, *task_args, **task_kwargs)
+        results.append(result)
+    return results

qiskit/utils/units.py

@@ -0,0 +1,143 @@
+# 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 numpy as np
+
+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]