qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/transpiler/timing_constraints.py

@@ -0,0 +1,59 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 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.
+
+"""Timing Constraints class."""
+
+from qiskit.transpiler.exceptions import TranspilerError
+
+
+class TimingConstraints:
+    """Hardware Instruction Timing Constraints."""
+
+    def __init__(
+        self,
+        granularity: int = 1,
+        min_length: int = 1,
+        pulse_alignment: int = 1,
+        acquire_alignment: int = 1,
+    ):
+        """Initialize a TimingConstraints object
+
+        Args:
+            granularity: An integer value representing minimum pulse gate
+                resolution in units of ``dt``. A user-defined pulse gate should have
+                duration of a multiple of this granularity value.
+            min_length: An integer value representing minimum pulse gate
+                length in units of ``dt``. A user-defined pulse gate should be longer
+                than this length.
+            pulse_alignment: An integer value representing a time resolution of gate
+                instruction starting time. Gate instruction should start at time which
+                is a multiple of the alignment value.
+            acquire_alignment: An integer value representing a time resolution of measure
+                instruction starting time. Measure instruction should start at time which
+                is a multiple of the alignment value.
+
+        Notes:
+            This information will be provided by the backend configuration.
+
+        Raises:
+            TranspilerError: When any invalid constraint value is passed.
+        """
+        self.granularity = granularity
+        self.min_length = min_length
+        self.pulse_alignment = pulse_alignment
+        self.acquire_alignment = acquire_alignment
+
+        for key, value in self.__dict__.items():
+            if not isinstance(value, int) or value < 1:
+                raise TranspilerError(
+                    f"Timing constraint {key} should be nonzero integer. Not {value}."
+                )

qiskit/user_config.py

@@ -0,0 +1,266 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2019.
+#
+# 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.
+
+"""Utils for reading a user preference config files."""
+
+import configparser
+import os
+from warnings import warn
+
+from qiskit import exceptions
+
+DEFAULT_FILENAME = os.path.join(os.path.expanduser("~"), ".qiskit", "settings.conf")
+
+
+class UserConfig:
+    """Class representing a user config file
+
+    The config file format should look like:
+
+    [default]
+    circuit_drawer = mpl
+    circuit_mpl_style = default
+    circuit_mpl_style_path = ~/.qiskit:<default location>
+    circuit_reverse_bits = True
+    circuit_idle_wires = False
+    transpile_optimization_level = 1
+    parallel = False
+    num_processes = 4
+    sabre_all_threads = true
+
+    """
+
+    def __init__(self, filename=None):
+        """Create a UserConfig
+
+        Args:
+            filename (str): The path to the user config file. If one isn't
+                specified, ~/.qiskit/settings.conf is used.
+        """
+        if filename is None:
+            self.filename = DEFAULT_FILENAME
+        else:
+            self.filename = filename
+        self.settings = {}
+        self.config_parser = configparser.ConfigParser()
+
+    def read_config_file(self):
+        """Read config file and parse the contents into the settings attr."""
+        if not os.path.isfile(self.filename):
+            return
+        self.config_parser.read(self.filename)
+        if "default" in self.config_parser.sections():
+            # Parse circuit_drawer
+            circuit_drawer = self.config_parser.get("default", "circuit_drawer", fallback=None)
+            if circuit_drawer:
+                if circuit_drawer not in ["text", "mpl", "latex", "latex_source", "auto"]:
+                    raise exceptions.QiskitUserConfigError(
+                        f"{circuit_drawer} is not a valid circuit drawer backend. Must be "
+                        "either 'text', 'mpl', 'latex', 'latex_source', or "
+                        "'auto'."
+                    )
+                self.settings["circuit_drawer"] = circuit_drawer
+
+            # Parse state_drawer
+            state_drawer = self.config_parser.get("default", "state_drawer", fallback=None)
+            if state_drawer:
+                valid_state_drawers = [
+                    "repr",
+                    "text",
+                    "latex",
+                    "latex_source",
+                    "qsphere",
+                    "hinton",
+                    "bloch",
+                ]
+                if state_drawer not in valid_state_drawers:
+                    valid_choices_string = "', '".join(c for c in valid_state_drawers)
+                    raise exceptions.QiskitUserConfigError(
+                        f"'{state_drawer}' is not a valid state drawer backend. "
+                        f"Choose from: '{valid_choices_string}'"
+                    )
+                self.settings["state_drawer"] = state_drawer
+
+            # Parse circuit_mpl_style
+            circuit_mpl_style = self.config_parser.get(
+                "default", "circuit_mpl_style", fallback=None
+            )
+            if circuit_mpl_style:
+                if not isinstance(circuit_mpl_style, str):
+                    warn(
+                        f"{circuit_mpl_style} is not a valid mpl circuit style. Must be "
+                        "a text string. Will not load style.",
+                        UserWarning,
+                        2,
+                    )
+                self.settings["circuit_mpl_style"] = circuit_mpl_style
+
+            # Parse circuit_mpl_style_path
+            circuit_mpl_style_path = self.config_parser.get(
+                "default", "circuit_mpl_style_path", fallback=None
+            )
+            if circuit_mpl_style_path:
+                cpath_list = circuit_mpl_style_path.split(":")
+                for path in cpath_list:
+                    if not os.path.exists(os.path.expanduser(path)):
+                        warn(
+                            f"{path} is not a valid circuit mpl style path."
+                            " Correct the path in ~/.qiskit/settings.conf.",
+                            UserWarning,
+                            2,
+                        )
+                self.settings["circuit_mpl_style_path"] = cpath_list
+
+            # Parse circuit_reverse_bits
+            try:
+                circuit_reverse_bits = self.config_parser.getboolean(
+                    "default", "circuit_reverse_bits", fallback=None
+                )
+            except ValueError as err:
+                raise exceptions.QiskitUserConfigError(
+                    f"Value assigned to circuit_reverse_bits is not valid. {str(err)}"
+                )
+            if circuit_reverse_bits is not None:
+                self.settings["circuit_reverse_bits"] = circuit_reverse_bits
+
+            # Parse circuit_idle_wires
+            try:
+                circuit_idle_wires = self.config_parser.getboolean(
+                    "default", "circuit_idle_wires", fallback=None
+                )
+            except ValueError as err:
+                raise exceptions.QiskitUserConfigError(
+                    f"Value assigned to circuit_idle_wires is not valid. {str(err)}"
+                )
+            if circuit_idle_wires is not None:
+                self.settings["circuit_idle_wires"] = circuit_idle_wires
+
+            # Parse transpile_optimization_level
+            transpile_optimization_level = self.config_parser.getint(
+                "default", "transpile_optimization_level", fallback=-1
+            )
+            if transpile_optimization_level != -1:
+                if transpile_optimization_level < 0 or transpile_optimization_level > 3:
+                    raise exceptions.QiskitUserConfigError(
+                        "%s is not a valid optimization level. Must be 0, 1, 2, or 3."
+                    )
+                self.settings["transpile_optimization_level"] = transpile_optimization_level
+
+            # Parse parallel
+            parallel_enabled = self.config_parser.getboolean("default", "parallel", fallback=None)
+            if parallel_enabled is not None:
+                self.settings["parallel_enabled"] = parallel_enabled
+
+            # Parse num_processes
+            num_processes = self.config_parser.getint("default", "num_processes", fallback=-1)
+            if num_processes != -1:
+                if num_processes <= 0:
+                    raise exceptions.QiskitUserConfigError(
+                        "%s is not a valid number of processes. Must be greater than 0"
+                    )
+                self.settings["num_processes"] = num_processes
+
+            # Parse sabre_all_threads
+            sabre_all_threads = self.config_parser.getboolean(
+                "default", "sabre_all_threads", fallback=None
+            )
+            if sabre_all_threads is not None:
+                self.settings["sabre_all_threads"] = sabre_all_threads
+
+
+def set_config(key, value, section=None, file_path=None):
+    """Adds or modifies a user configuration
+
+    It will add configuration to the currently configured location
+    or the value of file argument.
+
+    Only valid user config can be set in 'default' section. Custom
+    user config can be added in any other sections.
+
+    Changes to the existing config file will not be reflected in
+    the current session since the config file is parsed at import time.
+
+    Args:
+        key (str): name of the config
+        value (obj): value of the config
+        section (str, optional): if not specified, adds it to the
+            `default` section of the config file.
+        file_path (str, optional): the file to which config is added.
+            If not specified, adds it to the default config file or
+            if set, the value of `QISKIT_SETTINGS` env variable.
+
+    Raises:
+        QiskitUserConfigError: if the config is invalid
+    """
+    filename = file_path or os.getenv("QISKIT_SETTINGS", DEFAULT_FILENAME)
+    section = "default" if section is None else section
+
+    if not isinstance(key, str):
+        raise exceptions.QiskitUserConfigError("Key must be string type")
+
+    valid_config = {
+        "circuit_drawer",
+        "circuit_mpl_style",
+        "circuit_mpl_style_path",
+        "circuit_reverse_bits",
+        "circuit_idle_wires",
+        "transpile_optimization_level",
+        "parallel",
+        "num_processes",
+        "sabre_all_threads",
+    }
+
+    if section in [None, "default"]:
+        if key not in valid_config:
+            raise exceptions.QiskitUserConfigError(f"{key} is not a valid user config.")
+
+    config = configparser.ConfigParser()
+    config.read(filename)
+
+    if section not in config.sections():
+        config.add_section(section)
+
+    config.set(section, key, str(value))
+
+    try:
+        with open(filename, "w") as cfgfile:
+            config.write(cfgfile)
+    except OSError as ex:
+        raise exceptions.QiskitUserConfigError(
+            f"Unable to load the config file {filename}. Error: '{str(ex)}'"
+        )
+
+    # validates config
+    user_config = UserConfig(filename)
+    user_config.read_config_file()
+
+
+def get_config():
+    """Read the config file from the default location or env var.
+
+    It will read a config file at the location specified by the ``QISKIT_SETTINGS`` environment
+    variable if set, or ``$HOME/.qiskit/settings.conf`` if not.
+
+    If the environment variable ``QISKIT_IGNORE_USER_SETTINGS`` is set to the string ``TRUE``, this
+    will return an empty configuration, regardless of all other variables.
+
+    Returns:
+        dict: The settings dict from the parsed config file.
+    """
+    if os.getenv("QISKIT_IGNORE_USER_SETTINGS", "false").lower() == "true":
+        return {}
+    filename = os.getenv("QISKIT_SETTINGS", DEFAULT_FILENAME)
+    if not os.path.isfile(filename):
+        return {}
+    user_config = UserConfig(filename)
+    user_config.read_config_file()
+    return user_config.settings

qiskit/utils/__init__.py

@@ -0,0 +1,90 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2023.
+#
+# 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.
+
+
+"""
+===============================
+Utilities (:mod:`qiskit.utils`)
+===============================
+
+.. currentmodule:: qiskit.utils
+
+Deprecations
+============
+
+.. autofunction:: add_deprecation_to_docstring
+.. autofunction:: deprecate_arg
+.. autofunction:: deprecate_func
+
+SI unit conversion
+==================
+
+.. autofunction:: apply_prefix
+.. autofunction:: detach_prefix
+
+Class tools
+===========
+
+.. autofunction:: wrap_method
+
+Multiprocessing
+===============
+
+.. autofunction:: default_num_processes
+.. autofunction:: is_main_process
+.. autofunction:: local_hardware_info
+.. autofunction:: should_run_in_parallel
+
+A helper function for calling a custom function with Python
+:class:`~concurrent.futures.ProcessPoolExecutor`. Tasks can be executed in parallel using this function.
+
+.. autofunction:: parallel_map
+
+Optional Dependency Checkers
+============================
+
+.. automodule:: qiskit.utils.optionals
+"""
+
+from .deprecation import (
+    add_deprecation_to_docstring,
+    deprecate_arg,
+    deprecate_func,
+)
+from .units import apply_prefix, detach_prefix
+from .classtools import wrap_method
+from .lazy_tester import LazyDependencyManager, LazyImportTester, LazySubprocessTester
+
+from . import optionals
+
+from .parallel import (
+    parallel_map,
+    should_run_in_parallel,
+    local_hardware_info,
+    is_main_process,
+    default_num_processes,
+)
+
+__all__ = [
+    "LazyDependencyManager",
+    "LazyImportTester",
+    "LazySubprocessTester",
+    "add_deprecation_to_docstring",
+    "apply_prefix",
+    "default_num_processes",
+    "deprecate_arg",
+    "deprecate_func",
+    "is_main_process",
+    "local_hardware_info",
+    "parallel_map",
+    "should_run_in_parallel",
+]

qiskit/utils/classtools.py

@@ -0,0 +1,146 @@
+# 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.
+
+"""Tools useful for creating decorators, and other high-level callables."""
+
+import functools
+import inspect
+import types
+from typing import Type, Callable
+
+
+# On user-defined classes, `__new__` is magically inferred to be a staticmethod, `__init_subclass__`
+# is magically inferred to be a class method and `__prepare__` must be defined as a classmethod, but
+# the CPython types implemented in C (such as `object` and `type`) are `types.BuiltinMethodType`,
+# which we can't distinguish properly, so we need a little magic.
+_MAGIC_STATICMETHODS = {"__new__"}
+_MAGIC_CLASSMETHODS = {"__init_subclass__", "__prepare__"}
+
+
+class _lift_to_method:  # pylint: disable=invalid-name
+    """A decorator that ensures that an input callable object implements ``__get__``.  It is
+    returned unchanged if so, otherwise it is turned into the default implementation for functions,
+    which makes them bindable to instances.
+
+    Python-space functions and lambdas already have this behavior, but builtins like ``print``
+    don't; using this class allows us to do::
+
+        wrap_method(MyClass, "maybe_mutates_arguments", before=print, after=print)
+
+    to simply print all the arguments on entry and exit of the function, which otherwise wouldn't be
+    valid, since ``print`` isn't a descriptor.
+    """
+
+    __slots__ = ("_method",)
+
+    def __new__(cls, method):
+        if hasattr(method, "__get__"):
+            return method
+        return super().__new__(cls)
+
+    def __init__(self, method):
+        if method is self:
+            # Prevent double-initialization if we are passed an instance of this object to lift.
+            return
+        self._method = method
+
+    def __get__(self, obj, objtype):
+        # This is effectively the same implementation as `types.FunctionType.__get__`, but we can't
+        # bind that directly because it also includes a requirement that its `self` reference is of
+        # the correct type, and this isn't.
+        if obj is None:
+            return self._method
+        return types.MethodType(self._method, obj)
+
+
+class _WrappedMethod:
+    """Descriptor which calls its two arguments in succession, correctly handling instance- and
+    class-method calls.
+
+    It is intended that this class will replace the attribute that ``inner`` previously was on a
+    class or instance.  When accessed as that attribute, this descriptor will behave it is the same
+    function call, but with the ``function`` called before or after.
+    """
+
+    __slots__ = ("_method_decorator", "_method_has_get", "_method", "_before", "_after")
+
+    def __init__(self, method, before=None, after=None):
+        if isinstance(method, (classmethod, staticmethod)):
+            self._method_decorator = type(method)
+        elif isinstance(method, type(self)):
+            self._method_decorator = method._method_decorator
+        elif getattr(method, "__name__", None) in _MAGIC_STATICMETHODS:
+            self._method_decorator = staticmethod
+        elif getattr(method, "__name__", None) in _MAGIC_CLASSMETHODS:
+            self._method_decorator = classmethod
+        else:
+            self._method_decorator = _lift_to_method
+        before = (self._method_decorator(before),) if before is not None else ()
+        after = (self._method_decorator(after),) if after is not None else ()
+        if isinstance(method, type(self)):
+            self._method = method._method
+            self._before = before + method._before
+            self._after = method._after + after
+        else:
+            self._before = before
+            self._after = after
+            self._method = method
+        # If the inner method doesn't have `__get__` (like some builtin methods), it's faster to
+        # test a Boolean each time than the repeatedly raise and catch an exception, which is what
+        # `hasattr` does.
+        self._method_has_get = hasattr(self._method, "__get__")
+
+    def __get__(self, obj, objtype=None):
+        # `self._method` doesn't invoke the `_method` descriptor (if it is one) because that only
+        # happens for class variables. Here it's an instance variable, so we can pass through `obj`
+        # and `objtype` correctly like this.
+        method = self._method.__get__(obj, objtype) if self._method_has_get else self._method
+
+        @functools.wraps(method)
+        def out(*args, **kwargs):
+            for callback in self._before:
+                callback.__get__(obj, objtype)(*args, **kwargs)
+            retval = method(*args, **kwargs)
+            for callback in self._after:
+                callback.__get__(obj, objtype)(*args, **kwargs)
+            return retval
+
+        return out
+
+
+def wrap_method(cls: Type, name: str, *, before: Callable = None, after: Callable = None):
+    """Wrap the functionality the instance- or class method ``cls.name`` with additional behavior
+    ``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.
+
+    Args:
+        cls: the class to modify.
+        name: the name of the method on the class to wrap.
+        before: a callable that should be called before the method that is being wrapped.
+        after: 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.
+    """
+    # The best time to apply decorators to methods is before they are bound (e.g. by using function
+    # decorators during the class definition), but if we're making a class decorator, we can't do
+    # that.  We need the actual definition of the method, so we have to dodge the normal output of
+    # `type.__getattribute__`, which evalutes descriptors if it finds them.
+    method = inspect.getattr_static(cls, name)
+    setattr(cls, name, _WrappedMethod(method, before, after))