Utilities
qiskit.utils
Deprecations
add_deprecation_to_docstring
qiskit.utils.add_deprecation_to_docstring(func, msg, *, since, pending)
Dynamically insert the deprecation message into func
’s docstring.
Parameters
deprecate_arg
qiskit.utils.deprecate_arg(name, *, since, additional_msg=None, deprecation_description=None, pending=False, package_name='qiskit', new_alias=None, predicate=None, removal_timeline='no earlier than 3 months after the release date')
Decorator to indicate an argument has been deprecated in some way.
This decorator may be used multiple times on the same function, once per deprecated argument. It should be placed beneath other decorators like @staticmethod
and property decorators.
Parameters
- name (str) – The name of the deprecated argument.
- since (str) – The version the deprecation started at. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update since to the new version.
- deprecation_description (str | None) – What is being deprecated? E.g. “Setting my_func()’s my_arg argument to None.” If not set, will default to “{func_name}’s argument {name}”.
- additional_msg (str | None) – Put here any additional information, such as what to use instead (if new_alias is not set). For example, “Instead, use the argument new_arg, which is similar but does not impact the circuit’s setup.”
- pending (bool) – Set to True if the deprecation is still pending.
- package_name (str) – The PyPI package name, e.g. “qiskit-nature”.
- new_alias (str | None) – If the arg has simply been renamed, set this to the new name. The decorator will dynamically update the kwargs so that when the user sets the old arg, it will be passed in as the new_alias arg.
- predicate (Callable[[Any], bool] | None) – Only log the runtime warning if the predicate returns True. This is useful to deprecate certain values or types for an argument, e.g. lambda my_arg: isinstance(my_arg, dict). Regardless of if a predicate is set, the runtime warning will only log when the user specifies the argument.
- removal_timeline (str) – How soon can this deprecation be removed? Expects a value like “no sooner than 6 months after the latest release” or “in release 9.99”.
Returns
The decorated callable.
Return type
Callable
deprecate_arguments
qiskit.utils.deprecate_arguments(kwarg_map, category=<class 'DeprecationWarning'>, *, since=None)
Deprecated. Instead, use @deprecate_arg.
Parameters
- kwarg_map (dict[str, str | None]) – A dictionary of the old argument name to the new name.
- category (Type[Warning]) – Usually either DeprecationWarning or PendingDeprecationWarning.
- since (str | None) – The version the deprecation started at. Only Optional for backwards compatibility - this should always be set. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update since to the new version.
Returns
The decorated callable.
Return type
Callable
deprecate_func
qiskit.utils.deprecate_func(*, since, additional_msg=None, pending=False, package_name='qiskit', removal_timeline='no earlier than 3 months after the release date', is_property=False)
Decorator to indicate a function has been deprecated.
It should be placed beneath other decorators like @staticmethod and property decorators.
When deprecating a class, set this decorator on its __init__ function.
Parameters
- since (str) – The version the deprecation started at. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update
since
to the new version. - additional_msg (str | None) – Put here any additional information, such as what to use instead. For example, “Instead, use the function
new_func
from the module<my_module>.<my_submodule>
, which is similar but uses GPU acceleration.” - pending (bool) – Set to
True
if the deprecation is still pending. - package_name (str) – The PyPI package name, e.g. “qiskit-nature”.
- removal_timeline (str) – How soon can this deprecation be removed? Expects a value like “no sooner than 6 months after the latest release” or “in release 9.99”.
- is_property (bool) – If the deprecated function is a @property, set this to True so that the generated message correctly describes it as such. (This isn’t necessary for property setters, as their docstring is ignored by Python.)
Returns
The decorated callable.
Return type
Callable
deprecate_function
qiskit.utils.deprecate_function(msg, stacklevel=2, category=<class 'DeprecationWarning'>, *, since=None)
Deprecated. Instead, use @deprecate_func.
Parameters
- msg (str) – Warning message to emit.
- stacklevel (int) – The warning stacklevel to use, defaults to 2.
- category (Type[Warning]) – Usually either DeprecationWarning or PendingDeprecationWarning.
- since (str | None) – The version the deprecation started at. Only Optional for backwards compatibility - this should always be set. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update since to the new version.
Returns
The decorated, deprecated callable.
Return type
Callable
SI unit conversion
apply_prefix
qiskit.utils.apply_prefix(value, unit)
Given a SI unit prefix and value, apply the prefix to convert to standard SI unit.
Parameters
- value (float |ParameterExpression) – The number to apply prefix to.
- unit (str) – String prefix.
Returns
Converted value.
Return type
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.
Return type
detach_prefix
qiskit.utils.detach_prefix(value, decimal=None)
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
Parameters
- value (float) – The number to find prefix.
- decimal (int | None) – 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 withdecimal=3
or less.
Returns
A tuple of scaled value and prefix.
Return type
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.
Return type
Class tools
wrap_method
qiskit.utils.wrap_method(cls, name, *, before=None, after=None)
Wrap the functionality the instance- or class method cls.name
with additional behaviour before
and after
.
This mutates cls
, replacing the attribute name
with the new functionality. This is useful when creating class decorators. The method is allowed to be defined on any parent class instead.
If either before
or after
are given, they should be callables with a compatible signature to the method referred to. They will be called immediately before or after the method as appropriate, and any return value will be ignored.
Parameters
- cls (Type) – the class to modify.
- name (str) – the name of the method on the class to wrap.
- before (Callable | None) – a callable that should be called before the method that is being wrapped.
- after (Callable | None) – a callable that should be called after the method that is being wrapped.
Raises
ValueError – if the named method is not defined on the class or any parent class.
Multiprocessing
local_hardware_info
qiskit.utils.local_hardware_info()
Basic hardware information about the local machine.
Gives actual number of CPU’s in the machine, even when hyperthreading is turned on. CPU count defaults to 1 when true count can’t be determined.
Returns
The hardware information.
Return type
is_main_process
A helper function for calling a custom function with Python ProcessPoolExecutor
. Tasks can be executed in parallel using this function.
parallel_map
qiskit.utils.parallel_map(task, values, task_args=(), task_kwargs={}, num_processes=2)
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.
Parameters
- 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
The result list contains the value of task(value, *task_args, **task_kwargs)
for each value in values
.
Return type
result
Raises
QiskitError – If user interrupts via keyboard.
Examples
import time
from qiskit.utils import parallel_map
def func(_):
time.sleep(0.1)
return 0
parallel_map(func, list(range(10)));
Optional Dependency Checkers
Qiskit has several features that are enabled only if certain optional dependencies are satisfied. This module, qiskit.utils.optionals
, has a collection of objects that can be used to test if certain functionality is available, and optionally raise MissingOptionalLibraryError
if the functionality is not available.
Available Testers
Qiskit Components
qiskit.utils.optionals.HAS_AER | Qiskit Aer <https://qiskit.github.io/qiskit-aer/> provides high-performance simulators for the quantum circuits constructed within Qiskit. |
qiskit.utils.optionals.HAS_IBMQ | The Qiskit IBMQ Provider is used for accessing IBM Quantum hardware in the IBM cloud. |
qiskit.utils.optionals.HAS_IGNIS | Qiskit Ignis provides tools for quantum hardware verification, noise characterization, and error correction. |
qiskit.utils.optionals.HAS_TOQM | Qiskit TOQM provides transpiler passes for the Time-optimal Qubit mapping algorithm. |
External Python Libraries
qiskit.utils.optionals.HAS_CONSTRAINT | python-constraint is a constraint satisfaction problem solver, used in the CSPLayout transpiler pass. |
qiskit.utils.optionals.HAS_CPLEX | The IBM 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. |
qiskit.utils.optionals.HAS_CVXPY | CVXPY is a Python package for solving convex optimization problems. It is required for calculating diamond norms with quantum_info.diamond_norm() . |
qiskit.utils.optionals.HAS_DOCPLEX | IBM Decision Optimization CPLEX Modelling 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. |
qiskit.utils.optionals.HAS_FIXTURES | The test suite has additional features that are available if the optional fixtures module is installed. This generally also needs HAS_TESTTOOLS as well. This is generally only needed for Qiskit developers. |
qiskit.utils.optionals.HAS_IPYTHON | If the IPython kernel is available, certain additional visualisations and line magics are made available. |
qiskit.utils.optionals.HAS_IPYWIDGETS | Monitoring widgets for jobs running on external backends can be provided if ipywidgets is available. |
qiskit.utils.optionals.HAS_JAX | Some methods of gradient calculation within opflow.gradients require JAX for autodifferentiation. |
qiskit.utils.optionals.HAS_JUPYTER | Some of the tests require a complete Jupyter installation to test interactivity features. |
qiskit.utils.optionals.HAS_MATPLOTLIB | Qiskit provides several visualisation tools in the visualization module. Almost all of these are built using Matplotlib, which must be installed in order to use them. |
qiskit.utils.optionals.HAS_NETWORKX | No longer used by Qiskit. Internally, Qiskit now uses the high-performance rustworkx library as a core dependency, and during the change-over period, it was sometimes convenient to convert things into the Python-only NetworkX format. Some tests of application modules, such as Qiskit Nature still use NetworkX. |
qiskit.utils.optionals.HAS_NLOPT | NLopt is a nonlinear optimization library, used by the global optimizers in the algorithms.optimizers module. |
qiskit.utils.optionals.HAS_PIL | PIL is a Python image-manipulation library. Qiskit actually uses the pillow fork of PIL if it is available when generating certain visualizations, for example of both QuantumCircuit and DAGCircuit in certain modes. |
qiskit.utils.optionals.HAS_PYDOT | For some graph visualisations, Qiskit uses pydot as an interface to GraphViz (see HAS_GRAPHVIZ ). |
qiskit.utils.optionals.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. |
qiskit.utils.optionals.HAS_PYLATEX | Various LaTeX-based visualizations, especially the circuit drawers, need access to the pylatexenc project to work correctly. |
qiskit.utils.optionals.HAS_QASM3_IMPORT | The functions qasm3.load() and qasm3.loads() for importing OpenQASM 3 programs into QuantumCircuit instances use an external importer package. |
qiskit.utils.optionals.HAS_SEABORN | Qiskit provides several visualisation tools in the visualization module. Some of these are built using Seaborn, which must be installed in order to use them. |
qiskit.utils.optionals.HAS_SKLEARN | Some of the gradient functions in opflow.gradients use regularisation methods from Scikit Learn. |
qiskit.utils.optionals.HAS_SKQUANT | Some of the optimisers in algorithms.optimizers are based on those found in Scikit Quant, which must be installed to use them. |
qiskit.utils.optionals.HAS_SQSNOBFIT | SQSnobFit is a library for the “stable noisy optimization by branch and fit” algorithm. It is used by the SNOBFIT optimizer. |
qiskit.utils.optionals.HAS_SYMENGINE | Symengine is a fast C++ backend for the symbolic-manipulation library Sympy. Qiskit uses special methods from Symengine to accelerate its handling of Parameter s if available. |
qiskit.utils.optionals.HAS_TESTTOOLS | Qiskit’s test suite has more advanced functionality available if the optional testtools library is installed. This is generally only needed for Qiskit developers. |
qiskit.utils.optionals.HAS_TWEEDLEDUM | Tweedledum is an extension library for synthesis and optimization of circuits that may involve classical oracles. Qiskit’s PhaseOracle uses this, which is used in turn by amplification algorithms via the AmplificationProblem . |
qiskit.utils.optionals.HAS_Z3 | Z3 is a theorem prover, used in the CrosstalkAdaptiveSchedule and HoareOptimizer transpiler passes. |
External Command-Line Tools
qiskit.utils.optionals.HAS_GRAPHVIZ | For some graph visualisations, Qiskit uses the GraphViz visualisation tool via its pydot interface (see HAS_PYDOT ). |
qiskit.utils.optionals.HAS_PDFLATEX | Visualisation 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. |
qiskit.utils.optionals.HAS_PDFTOCAIRO | Visualisation tools that convert LaTeX-generated files into rasterised images use the pdftocairo tool. This is part of the Poppler suite of PDF tools. |
Lazy Checker Classes
Each of the lazy checkers is an instance of LazyDependencyManager
in one of its two subclasses: LazyImportTester
and LazySubprocessTester
. These should be imported from utils
directly if required, such as:
from qiskit.utils import LazyImportTester
LazyDependencyManager
class qiskit.utils.LazyDependencyManager(*, name=None, callback=None, install=None, msg=None)
A mananger for some optional features that are expensive to import, or to verify the existence of.
These objects can be used as Booleans, such as if x
, and will evaluate True
if the dependency they test for is available, and False
if not. The presence of the dependency will only be tested when the Boolean is evaluated, so it can be used as a runtime test in functions and methods without requiring an import-time test.
These objects also encapsulate the error handling if their dependency is not present, so you can do things such as:
from qiskit.utils import LazyImportManager
HAS_MATPLOTLIB = LazyImportManager("matplotlib")
@HAS_MATPLOTLIB.require_in_call
def my_visualisation():
...
def my_other_visualisation():
# ... some setup ...
HAS_MATPLOTLIB.require_now("my_other_visualisation")
...
def my_third_visualisation():
if HAS_MATPLOTLIB:
from matplotlib import pyplot
else:
...
In all of these cases, matplotlib
is not imported until the functions are entered. In the case of the decorator, matplotlib
is tested for import when the function is called for the first time. In the second and third cases, the loader attempts to import matplotlib
when the require_now()
method is called, or when the Boolean context is evaluated. For the require
methods, an error is raised if the library is not available.
This is the base class, which provides the Boolean context checking and error management. The concrete classes LazyImportTester
and LazySubprocessTester
provide convenient entry points for testing that certain symbols are importable from modules, or certain command-line tools are available, respectively.
Parameters
- name – the name of this optional dependency.
- callback – a callback that is called immediately after the availability of the library is tested with the result. This will only be called once.
- install – how to install this optional dependency. Passed to
MissingOptionalLibraryError
as thepip_install
parameter. - msg – an extra message to include in the error raised if this is required.
_is_available
abstract _is_available()
Subclasses of LazyDependencyManager
should override this method to implement the actual test of availability. This method should return a Boolean, where True
indicates that the dependency was available. This method will only ever be called once.
Return type
disable_locally
disable_locally()
Create a context, during which the value of the dependency manager will be False
. This means that within the context, any calls to this object will behave as if the dependency is not available, including raising errors. It is valid to call this method whether or not the dependency has already been evaluated. This is most useful in tests.
require_in_call
require_in_call(feature_or_callable: Callable) → Callable
require_in_call(feature_or_callable: str) → Callable[[Callable], Callable]
Create a decorator for callables that requires that the dependency is available when the decorated function or method is called.
Parameters
feature_or_callable (str or Callable) – the name of the feature that requires these dependencies. If this function is called directly as a decorator (for example @HAS_X.require_in_call
as opposed to @HAS_X.require_in_call("my feature")
), then the feature name will be taken to be the function name, or class and method name as appropriate.
Returns
a decorator that will make its argument require this dependency before it is called.
Return type
Callable
require_in_instance
require_in_instance(feature_or_class: Type) → Type
require_in_instance(feature_or_class: str) → Callable[[Type], Type]
A class decorator that requires the dependency is available when the class is initialised. This decorator can be used even if the class does not define an __init__
method.
Parameters
feature_or_class (str orType) – the name of the feature that requires these dependencies. If this function is called directly as a decorator (for example @HAS_X.require_in_instance
as opposed to @HAS_X.require_in_instance("my feature")
), then the feature name will be taken as the name of the class.
Returns
a class decorator that ensures that the wrapped feature is present if the class is initialised.
Return type
Callable
require_now
require_now(feature)
Eagerly attempt to import the dependencies in this object, and raise an exception if they cannot be imported.
Parameters
feature (str) – the name of the feature that is requiring these dependencies.
Raises
MissingOptionalLibraryError – if the dependencies cannot be imported.
LazyImportTester
class qiskit.utils.LazyImportTester(name_map_or_modules, *, name=None, callback=None, install=None, msg=None)
A lazy dependency tester for importable Python modules. Any required objects will only be imported at the point that this object is tested for its Boolean value.
Parameters
name_map_or_modules (str |Dict[str, Iterable[str]] | Iterable[str]) – if a name map, then a dictionary where the keys are modules or packages, and the values are iterables of names to try and import from that module. It should be valid to write from <module> import <name1>, <name2>, ...
. If simply a string or iterable of strings, then it should be valid to write import <module>
for each of them.
Raises
ValueError – if no modules are given.
LazySubprocessTester
class qiskit.utils.LazySubprocessTester(command, *, name=None, callback=None, install=None, msg=None)
A lazy checker that a command-line tool is available. The command will only be run once, at the point that this object is checked for its Boolean value.
Parameters
command (str |Iterable[str]) – the strings that make up the command to be run. For example, ["pdflatex", "-version"]
.
Raises
ValueError – if an empty command is given.