qiskit 1.3.0__cp39-abi3-win32.whl

qiskit/providers/models/pulsedefaults.py

@@ -0,0 +1,305 @@
+# 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.
+
+
+"""Model and schema for pulse defaults."""
+import warnings
+from typing import Any, Dict, List
+
+from qiskit.pulse.instruction_schedule_map import InstructionScheduleMap, PulseQobjDef
+from qiskit.qobj import PulseLibraryItem, PulseQobjInstruction
+from qiskit.qobj.converters import QobjToInstructionConverter
+from qiskit.utils.deprecate_pulse import deprecate_pulse_dependency
+
+
+class MeasurementKernel:
+    """Class representing a Measurement Kernel."""
+
+    def __init__(self, name, params):
+        """Initialize a MeasurementKernel object
+
+        Args:
+            name (str): The name of the measurement kernel
+            params: The parameters of the measurement kernel
+        """
+        self.name = name
+        self.params = params
+
+    def to_dict(self):
+        """Return a dictionary format representation of the MeasurementKernel.
+
+        Returns:
+            dict: The dictionary form of the MeasurementKernel.
+        """
+        return {"name": self.name, "params": self.params}
+
+    @classmethod
+    def from_dict(cls, data):
+        """Create a new MeasurementKernel object from a dictionary.
+
+        Args:
+            data (dict): A dictionary representing the MeasurementKernel
+                         to create. It will be in the same format as output by
+                         :meth:`to_dict`.
+
+        Returns:
+            MeasurementKernel: The MeasurementKernel from the input dictionary.
+        """
+        return cls(**data)
+
+
+class Discriminator:
+    """Class representing a Discriminator."""
+
+    def __init__(self, name, params):
+        """Initialize a Discriminator object
+
+        Args:
+            name (str): The name of the discriminator
+            params: The parameters of the discriminator
+        """
+        self.name = name
+        self.params = params
+
+    def to_dict(self):
+        """Return a dictionary format representation of the Discriminator.
+
+        Returns:
+            dict: The dictionary form of the Discriminator.
+        """
+        return {"name": self.name, "params": self.params}
+
+    @classmethod
+    def from_dict(cls, data):
+        """Create a new Discriminator object from a dictionary.
+
+        Args:
+            data (dict): A dictionary representing the Discriminator
+                         to create. It will be in the same format as output by
+                         :meth:`to_dict`.
+
+        Returns:
+            Discriminator: The Discriminator from the input dictionary.
+        """
+        return cls(**data)
+
+
+class Command:
+    """Class representing a Command.
+
+    Attributes:
+        name: Pulse command name.
+    """
+
+    _data = {}
+
+    def __init__(self, name: str, qubits=None, sequence=None, **kwargs):
+        """Initialize a Command object
+
+        Args:
+            name (str): The name of the command
+            qubits: The qubits for the command
+            sequence (PulseQobjInstruction): The sequence for the Command
+            kwargs: Optional additional fields
+        """
+        self._data = {}
+        self.name = name
+        if qubits is not None:
+            self.qubits = qubits
+        if sequence is not None:
+            self.sequence = sequence
+        self._data.update(kwargs)
+
+    def __getattr__(self, name):
+        try:
+            return self._data[name]
+        except KeyError as ex:
+            raise AttributeError(f"Attribute {name} is not defined") from ex
+
+    def to_dict(self):
+        """Return a dictionary format representation of the Command.
+
+        Returns:
+            dict: The dictionary form of the Command.
+        """
+        out_dict = {"name": self.name}
+        if hasattr(self, "qubits"):
+            out_dict["qubits"] = self.qubits
+        if hasattr(self, "sequence"):
+            out_dict["sequence"] = [x.to_dict() for x in self.sequence]
+        out_dict.update(self._data)
+        return out_dict
+
+    @classmethod
+    def from_dict(cls, data):
+        """Create a new Command object from a dictionary.
+
+        Args:
+            data (dict): A dictionary representing the ``Command``
+                         to create. It will be in the same format as output by
+                         :meth:`to_dict`.
+
+        Returns:
+            Command: The ``Command`` from the input dictionary.
+        """
+        # Pulse command data is nested dictionary.
+        # To avoid deepcopy and avoid mutating the source object, create new dict here.
+        in_data = {}
+        for key, value in data.items():
+            if key == "sequence":
+                in_data[key] = list(map(PulseQobjInstruction.from_dict, value))
+            else:
+                in_data[key] = value
+        return cls(**in_data)
+
+
+class PulseDefaults:
+    """Description of default settings for Pulse systems. These are instructions or settings that
+    may be good starting points for the Pulse user. The user may modify these defaults for custom
+    scheduling.
+    """
+
+    _data = {}
+
+    @deprecate_pulse_dependency
+    def __init__(
+        self,
+        qubit_freq_est: List[float],
+        meas_freq_est: List[float],
+        buffer: int,
+        pulse_library: List[PulseLibraryItem],
+        cmd_def: List[Command],
+        meas_kernel: MeasurementKernel = None,
+        discriminator: Discriminator = None,
+        **kwargs: Dict[str, Any],
+    ):
+        """
+        Validate and reformat transport layer inputs to initialize.
+        Args:
+            qubit_freq_est: Estimated qubit frequencies in GHz.
+            meas_freq_est: Estimated measurement cavity frequencies in GHz.
+            buffer: Default buffer time (in units of dt) between pulses.
+            pulse_library: Pulse name and sample definitions.
+            cmd_def: Operation name and definition in terms of Commands.
+            meas_kernel: The measurement kernels
+            discriminator: The discriminators
+            **kwargs: Other attributes for the super class.
+        """
+        self._data = {}
+        self.buffer = buffer
+        self.qubit_freq_est = [freq * 1e9 for freq in qubit_freq_est]
+        """Qubit frequencies in Hertz."""
+        self.meas_freq_est = [freq * 1e9 for freq in meas_freq_est]
+        """Measurement frequencies in Hertz."""
+        self.pulse_library = pulse_library
+        self.cmd_def = cmd_def
+        self.instruction_schedule_map = InstructionScheduleMap()
+        self.converter = QobjToInstructionConverter(pulse_library)
+
+        for inst in cmd_def:
+            entry = PulseQobjDef(converter=self.converter, name=inst.name)
+            entry.define(inst.sequence, user_provided=False)
+            self.instruction_schedule_map._add(
+                instruction_name=inst.name,
+                qubits=tuple(inst.qubits),
+                entry=entry,
+            )
+
+        if meas_kernel is not None:
+            self.meas_kernel = meas_kernel
+        if discriminator is not None:
+            self.discriminator = discriminator
+
+        self._data.update(kwargs)
+
+    def __getattr__(self, name):
+        try:
+            return self._data[name]
+        except KeyError as ex:
+            raise AttributeError(f"Attribute {name} is not defined") from ex
+
+    def to_dict(self):
+        """Return a dictionary format representation of the PulseDefaults.
+        Returns:
+            dict: The dictionary form of the PulseDefaults.
+        """
+        out_dict = {
+            "qubit_freq_est": self.qubit_freq_est,
+            "meas_freq_est": self.qubit_freq_est,
+            "buffer": self.buffer,
+            "pulse_library": [x.to_dict() for x in self.pulse_library],
+            "cmd_def": [x.to_dict() for x in self.cmd_def],
+        }
+        if hasattr(self, "meas_kernel"):
+            out_dict["meas_kernel"] = self.meas_kernel.to_dict()
+        if hasattr(self, "discriminator"):
+            out_dict["discriminator"] = self.discriminator.to_dict()
+        for key, value in self.__dict__.items():
+            if key not in [
+                "qubit_freq_est",
+                "meas_freq_est",
+                "buffer",
+                "pulse_library",
+                "cmd_def",
+                "meas_kernel",
+                "discriminator",
+                "converter",
+                "instruction_schedule_map",
+            ]:
+                out_dict[key] = value
+        out_dict.update(self._data)
+
+        out_dict["qubit_freq_est"] = [freq * 1e-9 for freq in self.qubit_freq_est]
+        out_dict["meas_freq_est"] = [freq * 1e-9 for freq in self.meas_freq_est]
+        return out_dict
+
+    @classmethod
+    def from_dict(cls, data):
+        """Create a new PulseDefaults object from a dictionary.
+
+        Args:
+            data (dict): A dictionary representing the PulseDefaults
+                         to create. It will be in the same format as output by
+                         :meth:`to_dict`.
+        Returns:
+            PulseDefaults: The PulseDefaults from the input dictionary.
+        """
+        schema = {
+            "pulse_library": PulseLibraryItem,  # The class PulseLibraryItem is deprecated
+            "cmd_def": Command,
+            "meas_kernel": MeasurementKernel,
+            "discriminator": Discriminator,
+        }
+
+        # Pulse defaults data is nested dictionary.
+        # To avoid deepcopy and avoid mutating the source object, create new dict here.
+        in_data = {}
+        for key, value in data.items():
+            if key in schema:
+                with warnings.catch_warnings():
+                    # The class PulseLibraryItem is deprecated
+                    warnings.filterwarnings("ignore", category=DeprecationWarning, module="qiskit")
+                    if isinstance(value, list):
+                        in_data[key] = list(map(schema[key].from_dict, value))
+                    else:
+                        in_data[key] = schema[key].from_dict(value)
+            else:
+                in_data[key] = value
+
+        return cls(**in_data)
+
+    def __str__(self):
+        qubit_freqs = [freq / 1e9 for freq in self.qubit_freq_est]
+        meas_freqs = [freq / 1e9 for freq in self.meas_freq_est]
+        qfreq = f"Qubit Frequencies [GHz]\n{qubit_freqs}"
+        mfreq = f"Measurement Frequencies [GHz]\n{meas_freqs} "
+        return f"<{self.__class__.__name__}({str(self.instruction_schedule_map)}{qfreq}\n{mfreq})>"

qiskit/providers/options.py

@@ -0,0 +1,273 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 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.
+
+"""Container class for backend options."""
+
+import io
+from collections.abc import Mapping
+
+
+class Options(Mapping):
+    """Base options object
+
+    This class is what all backend options are based
+    on. The properties of the class are intended to be all dynamically
+    adjustable so that a user can reconfigure the backend on demand. If a
+    property is immutable to the user (eg something like number of qubits)
+    that should be a configuration of the backend class itself instead of the
+    options.
+
+    Instances of this class behave like dictionaries. Accessing an
+    option with a default value can be done with the `get()` method:
+
+    >>> options = Options(opt1=1, opt2=2)
+    >>> options.get("opt1")
+    1
+    >>> options.get("opt3", default="hello")
+    'hello'
+
+    Key-value pairs for all options can be retrieved using the `items()` method:
+
+    >>> list(options.items())
+    [('opt1', 1), ('opt2', 2)]
+
+    Options can be updated by name:
+
+    >>> options["opt1"] = 3
+    >>> options.get("opt1")
+    3
+
+    Runtime validators can be registered. See `set_validator`.
+    Updates through `update_options` and indexing (`__setitem__`) validate
+    the new value before performing the update and raise `ValueError` if
+    the new value is invalid.
+
+    >>> options.set_validator("opt1", (1, 5))
+    >>> options["opt1"] = 4
+    >>> options["opt1"]
+    4
+    >>> options["opt1"] = 10  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    ValueError: ...
+    """
+
+    # Here there are dragons.
+
+    # This class preamble is an abhorrent hack to make `Options` work similarly to a
+    # SimpleNamespace, but with its instance methods and attributes in a separate namespace.  This
+    # is required to make the initial release of Qiskit Terra 0.19 compatible with already released
+    # versions of Qiskit Experiments, which rely on both of
+    #       options.my_key = my_value
+    #       transpile(qc, **options.__dict__)
+    # working.
+    #
+    # Making `__dict__` a property which gets a slotted attribute solves the second line.  The
+    # slotted attributes are not stored in a `__dict__` anyway, and `__slots__` classes suppress the
+    # creation of `__dict__`.  That leaves it free for us to override it with a property, which
+    # returns the options namespace `_fields`.
+    #
+    # We need to make attribute setting simply set options as well, to support statements of the
+    # form `options.key = value`.  We also need to ensure that existing uses do not override any new
+    # methods.  We do this by overriding `__setattr__` to purely write into our `_fields` dict
+    # instead.  This has the highly unusual behavior that
+    #       >>> options = Options()
+    #       >>> options.validator = "my validator option setting"
+    #       >>> options.validator
+    #       {}
+    #       >>> options.get("validator")
+    #       "my validator option setting"
+    # This is the most we can do to support the old interface; _getting_ attributes must return the
+    # new forms where appropriate, but setting will work with anything.  All options can always be
+    # returned by `Options.get`.  To initialise the attributes in `__init__`, we need to dodge the
+    # overriding of `__setattr__`, and upcall to `object.__setattr__`.
+    #
+    # To support copying and pickling, we also have to define how to set our state, because Python's
+    # normal way of trying to get attributes in the unpickle will fail.
+    #
+    # This is a terrible hack, and is purely to ensure that Terra 0.19 does not break versions of
+    # other Qiskit-family packages that are already deployed.  It should be removed as soon as
+    # possible.
+
+    __slots__ = ("_fields", "validator")
+
+    # implementation of the Mapping ABC:
+
+    def __getitem__(self, key):
+        return self._fields[key]
+
+    def __iter__(self):
+        return iter(self._fields)
+
+    def __len__(self):
+        return len(self._fields)
+
+    # Allow modifying the options (validated)
+
+    def __setitem__(self, key, value):
+        self.update_options(**{key: value})
+
+    # backwards-compatibility with Qiskit Experiments:
+
+    @property
+    def __dict__(self):
+        return self._fields
+
+    # SimpleNamespace-like access to options:
+
+    def __getattr__(self, name):
+        # This does not interrupt the normal lookup of things like methods or `_fields`, because
+        # those are successfully resolved by the normal Python lookup apparatus.  If we are here,
+        # then lookup has failed, so we must be looking for an option.  If the user has manually
+        # called `self.__getattr__("_fields")` then they'll get the option not the full dict, but
+        # that's not really our fault.  `getattr(self, "_fields")` will still find the dict.
+        try:
+            return self._fields[name]
+        except KeyError as ex:
+            raise AttributeError(f"Option {name} is not defined") from ex
+
+    # setting options with the namespace interface is not validated
+    def __setattr__(self, key, value):
+        self._fields[key] = value
+
+    # custom pickling:
+
+    def __getstate__(self):
+        return (self._fields, self.validator)
+
+    def __setstate__(self, state):
+        _fields, validator = state
+        super().__setattr__("_fields", _fields)
+        super().__setattr__("validator", validator)
+
+    def __copy__(self):
+        """Return a copy of the Options.
+
+        The returned option and validator values are shallow copies of the originals.
+        """
+        out = self.__new__(type(self))  # pylint:disable=no-value-for-parameter
+        out.__setstate__((self._fields.copy(), self.validator.copy()))
+        return out
+
+    def __init__(self, **kwargs):
+        super().__setattr__("_fields", kwargs)
+        super().__setattr__("validator", {})
+
+    # The eldritch horrors are over, and normal service resumes below.  Beware that while
+    # `__setattr__` is overridden, you cannot do `self.x = y` (but `self.x[key] = y` is fine).  This
+    # should not be necessary, but if _absolutely_ required, you must do
+    #       super().__setattr__("x", y)
+    # to avoid just setting a value in `_fields`.
+
+    def __repr__(self):
+        items = (f"{k}={v!r}" for k, v in self._fields.items())
+        return f"{type(self).__name__}({', '.join(items)})"
+
+    def __eq__(self, other):
+        if isinstance(self, Options) and isinstance(other, Options):
+            return self._fields == other._fields
+        return NotImplemented
+
+    def set_validator(self, field, validator_value):
+        """Set an optional validator for a field in the options
+
+        Setting a validator enables changes to an options values to be
+        validated for correctness when :meth:`~qiskit.providers.Options.update_options`
+        is called. For example if you have a numeric field like
+        ``shots`` you can specify a bounds tuple that set an upper and lower
+        bound on the value such as::
+
+            options.set_validator("shots", (1, 4096))
+
+        In this case whenever the ``"shots"`` option is updated by the user
+        it will enforce that the value is >=1 and <=4096. A ``ValueError`` will
+        be raised if it's outside those bounds. If a validator is already present
+        for the specified field it will be silently overridden.
+
+        Args:
+            field (str): The field name to set the validator on
+            validator_value (list or tuple or type): The value to use for the
+                validator depending on the type indicates on how the value for
+                a field is enforced. If a tuple is passed in it must have a
+                length of two and will enforce the min and max value
+                (inclusive) for an integer or float value option. If it's a
+                list it will list the valid values for a field. If it's a
+                ``type`` the validator will just enforce the value is of a
+                certain type.
+        Raises:
+            KeyError: If field is not present in the options object
+            ValueError: If the ``validator_value`` has an invalid value for a
+                given type
+            TypeError: If ``validator_value`` is not a valid type
+        """
+
+        if field not in self._fields:
+            raise KeyError(f"Field '{field}' is not present in this options object")
+        if isinstance(validator_value, tuple):
+            if len(validator_value) != 2:
+                raise ValueError(
+                    "A tuple validator must be of the form '(lower, upper)' "
+                    "where lower and upper are the lower and upper bounds "
+                    "inclusive of the numeric value"
+                )
+        elif isinstance(validator_value, list):
+            if len(validator_value) == 0:
+                raise ValueError("A list validator must have at least one entry")
+        elif isinstance(validator_value, type):
+            pass
+        else:
+            raise TypeError(
+                f"{type(validator_value)} is not a valid validator type, it "
+                "must be a tuple, list, or class/type"
+            )
+        self.validator[field] = validator_value  # pylint: disable=unsupported-assignment-operation
+
+    def update_options(self, **fields):
+        """Update options with kwargs"""
+        for field_name, field in fields.items():
+            field_validator = self.validator.get(field_name, None)
+            if isinstance(field_validator, tuple):
+                if field > field_validator[1] or field < field_validator[0]:
+                    raise ValueError(
+                        f"Specified value for '{field_name}' is not a valid value, "
+                        f"must be >={field_validator[0]} or <={field_validator[1]}"
+                    )
+            elif isinstance(field_validator, list):
+                if field not in field_validator:
+                    raise ValueError(
+                        f"Specified value for {field_name} is not a valid choice, "
+                        f"must be one of {field_validator}"
+                    )
+            elif isinstance(field_validator, type):
+                if not isinstance(field, field_validator):
+                    raise TypeError(
+                        f"Specified value for {field_name} is not of required type {field_validator}"
+                    )
+
+        self._fields.update(fields)
+
+    def __str__(self):
+        no_validator = super().__str__()
+        if not self.validator:
+            return no_validator
+        else:
+            out_str = io.StringIO()
+            out_str.write(no_validator)
+            out_str.write("\nWhere:\n")
+            for field, value in self.validator.items():
+                if isinstance(value, tuple):
+                    out_str.write(f"\t{field} is >= {value[0]} and <= {value[1]}\n")
+                elif isinstance(value, list):
+                    out_str.write(f"\t{field} is one of {value}\n")
+                elif isinstance(value, type):
+                    out_str.write(f"\t{field} is of type {value}\n")
+            return out_str.getvalue()

qiskit/providers/provider.py

@@ -0,0 +1,95 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 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.
+
+"""Base class for a provider."""
+
+from abc import ABC, abstractmethod
+
+from qiskit.providers.exceptions import QiskitBackendNotFoundError
+from qiskit.utils import deprecate_func
+
+
+class Provider:
+    """Base common type for all versioned Provider abstract classes.
+
+    Note this class should not be inherited from directly, it is intended
+    to be used for type checking. When implementing a provider you should use
+    the versioned abstract classes as the parent class and not this class
+    directly.
+    """
+
+    version = 0
+
+    @deprecate_func(
+        since=1.1,
+        additional_msg="The abstract Provider and ProviderV1 classes are deprecated and will be "
+        "removed in 2.0. You can just remove it as the parent class and a `get_backend` "
+        "method that returns the backends from `self.backend`.",
+    )
+    def __init__(self):
+        pass
+
+
+class ProviderV1(Provider, ABC):
+    """Base class for a Backend Provider."""
+
+    version = 1
+
+    @deprecate_func(
+        since=1.1,
+        additional_msg="The abstract Provider and ProviderV1 classes are deprecated and will  be "
+        "removed in 2.0. You can just remove it as the parent class and a `get_backend` "
+        "method that returns the backends from `self.backend`.",
+    )
+    def get_backend(self, name=None, **kwargs):
+        """Return a single backend matching the specified filtering.
+
+        Args:
+            name (str): name of the backend.
+            **kwargs: dict used for filtering.
+
+        Returns:
+            Backend: a backend matching the filtering.
+
+        Raises:
+            QiskitBackendNotFoundError: if no backend could be found or
+                more than one backend matches the filtering criteria.
+        """
+        backends = self.backends(name, **kwargs)
+        if len(backends) > 1:
+            raise QiskitBackendNotFoundError("More than one backend matches the criteria")
+        if not backends:
+            raise QiskitBackendNotFoundError("No backend matches the criteria")
+
+        return backends[0]
+
+    @abstractmethod
+    def backends(self, name=None, **kwargs):
+        """Return a list of backends matching the specified filtering.
+
+        Args:
+            name (str): name of the backend.
+            **kwargs: dict used for filtering.
+
+        Returns:
+            list[Backend]: a list of Backends that match the filtering
+                criteria.
+        """
+        pass
+
+    def __eq__(self, other):
+        """Equality comparison.
+
+        By default, it is assumed that two `Providers` from the same class are
+        equal. Subclassed providers can override this behavior.
+        """
+        return type(self).__name__ == type(other).__name__