Utilities

qiskit.utils.add_deprecation_to_docstring(func, msg, *, since, pending)

Dynamically insert the deprecation message into func’s docstring.

Parameters

• func (Callable) – The function to modify.
• msg (str) – The full deprecation message.
• since (str | None) – The version the deprecation started at.
• pending (bool) – Is the deprecation still pending?

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

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

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

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

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

dict

qiskit.utils.is_main_process()

Checks whether the current process is the main one

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

float | ParameterExpression

Raises

ValueError – If the units aren’t recognized.

Return type

float | ParameterExpression

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 with decimal=3 or less.

Returns

A tuple of scaled value and prefix.

Return type

tuple[float, str]

Raises

• ValueError – If the value is out of range.
• ValueError – If the value is not real number.

Return type

tuple[float, str]

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.

qiskit.utils.summarize_circuits(circuits)

Summarize circuits based on QuantumCircuit, and five metrics are summarized.

• Number of qubits
• Number of classical bits
• Number of operations
• Depth of circuits
• Counts of different gate operations

The average statistic of the first four is provided if multiple circuits are provided.

Deprecated since version 0.46.0

The function qiskit.utils.circuit_utils.summarize_circuits() is deprecated as of qiskit 0.46.0. It will be removed in the Qiskit 1.0 release. This function was only used in the context of qiskit.opflow/qiskit.algorithms, two modules deprecated and planned to be removed in Qiskit 1.0.

Parameters

circuits (QuantumCircuit or [QuantumCircuit]) – the to-be-summarized circuits

Returns

a formatted string records the summary

Return type

str

qiskit.utils.get_entangler_map(map_type, num_qubits, offset=0)

Utility method to get an entangler map among qubits.

Parameters

• map_type (str) – ‘full’ entangles each qubit with all the subsequent ones ‘linear’ entangles each qubit with the next ‘sca’ (shifted circular alternating entanglement) is a circular entanglement where the ‘long’ entanglement is shifted by one position every block and every block the role or control/target qubits alternate
• num_qubits (int) – Number of qubits for which the map is needed
• offset (int) – Some map_types (e.g. ‘sca’) can shift the gates in the entangler map by the specified integer offset.

Returns

A map of qubit index to an array of indexes to which this should be entangled

Return type

list

Raises

ValueError – if map_type is not valid.

qiskit.utils.validate_entangler_map(entangler_map, num_qubits, allow_double_entanglement=False)

Validate a user supplied entangler map and converts entries to ints.

Parameters

• entangler_map (list[list]) – An entangler map, keys are source qubit index (int), value is array of target qubit index(es) (int)
• num_qubits (int) – Number of qubits
• allow_double_entanglement (bool) – If we allow in two qubits can be entangled each other

Returns

Validated/converted map

Return type

list

Raises

• TypeError – entangler map is not list type or list of list
• ValueError – the index of entangler map is out of range
• ValueError – the qubits are cross-entangled.

qiskit.utils.has_ibmq()

Check if IBMQ is installed.

qiskit.utils.has_aer()

Check if Aer is installed.

qiskit.utils.name_args(mapping, skip=0)

Decorator to convert unnamed arguments to named ones.

Can be used to deprecate old signatures of a function, e.g.

old_f(a: TypeA, b: TypeB, c: TypeC)
new_f(a: TypeA, d: TypeD, b: TypeB=None, c: TypeC=None)

Then, to support the old signature this decorator can be used as

@name_args([
    ('a'),  # stays the same
    ('d', {TypeB: 'b'}),  # if arg is of type TypeB, call if 'b' else 'd'
    ('b', {TypeC: 'c'})
])
def new_f(a: TypeA, d: TypeD, b: TypeB=None, c: TypeC=None):
    if b is not None:
        # raise warning, this is deprecated!
    if c is not None:
        # raise warning, this is deprecated!

Default value: <qiskit.utils.algorithm_globals.QiskitAlgorithmGlobals object>

Class for global properties.

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.tools.parallel import parallel_map
def func(_):
        time.sleep(0.1)
        return 0
parallel_map(func, list(range(10)));

Qiskit Aer provides high-performance simulators for the quantum circuits constructed within Qiskit.

The Qiskit IBMQ Provider was historically used for accessing IBM Quantum hardware in the IBM cloud, but is now archived.

Qiskit Ignis was historically used to provide tools for quantum hardware verification, noise characterization, and error correction, but is now archived.

Qiskit TOQM provides transpiler passes for the Time-optimal Qubit mapping algorithm.

python-constraint is a constraint satisfaction problem solver, used in the CSPLayout transpiler pass.

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 was historically and the optional remains for backwards compatibility.

CVXPY is a Python package for solving convex optimization problems. It is required for calculating diamond norms with quantum_info.diamond_norm().

IBM Decision Optimization CPLEX Modelling is a library for prescriptive analysis. Like CPLEX, this is no longer by Qiskit, but it was historically and the optional remains for backwards compatibility.

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.

If the IPython kernel is available, certain additional visualisations and line magics are made available.

Monitoring widgets for jobs running on external backends can be provided if ipywidgets is available.

Some methods of gradient calculation within opflow.gradients require JAX for autodifferentiation.

Some of the tests require a complete Jupyter installation to test interactivity features.

Qiskit provides several visualization tools in the visualization module. Almost all of these are built using Matplotlib, which must be installed in order to use them.

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.

NLopt is a nonlinear optimization library, used by the global optimizers in the algorithms.optimizers module.

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.

For some graph visualizations, Qiskit uses pydot as an interface to GraphViz (see HAS_GRAPHVIZ).

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.

Various LaTeX-based visualizations, especially the circuit drawers, need access to the pylatexenc project to work correctly.

The functions qasm3.load() and qasm3.loads() for importing OpenQASM 3 programs into QuantumCircuit instances use an external importer package.

Qiskit provides several visualization tools in the visualization module. Some of these are built using Seaborn, which must be installed in order to use them.

Some of the gradient functions in opflow.gradients use regularisation methods from Scikit Learn.

Some of the optimisers in algorithms.optimizers are based on those found in Scikit Quant, which must be installed to use them.

SQSnobFit is a library for the “stable noisy optimization by branch and fit” algorithm. It is used by the SNOBFIT optimizer.

Symengine is a fast C++ backend for the symbolic-manipulation library Sympy. Qiskit uses special methods from Symengine to accelerate its handling of Parameters if available.

Qiskit’s test suite has more advanced functionality available if the optional testtools library is installed. This is generally only needed for Qiskit developers.

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.

Z3 is a theorem prover, used in the CrosstalkAdaptiveSchedule and HoareOptimizer transpiler passes.

For some graph visualizations, Qiskit uses the GraphViz visualization tool via its pydot interface (see HAS_PYDOT).

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.

Visualization tools that convert LaTeX-generated files into rasterized images use the pdftocairo tool. This is part of the Poppler suite of PDF tools.