qiskit 1.0.0b1__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

qiskit/pulse/library/pulse.py

@@ -0,0 +1,137 @@
+# 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.
+
+"""Pulses are descriptions of waveform envelopes. They can be transmitted by control electronics
+to the device.
+"""
+from abc import ABC, abstractmethod
+from typing import Dict, Optional, Any, Tuple, Union
+
+from qiskit.circuit.parameterexpression import ParameterExpression
+
+
+class Pulse(ABC):
+    """The abstract superclass for pulses. Pulses are complex-valued waveform envelopes. The
+    modulation phase and frequency are specified separately from ``Pulse``s.
+    """
+
+    __slots__ = ("duration", "name", "_limit_amplitude")
+
+    limit_amplitude = True
+
+    @abstractmethod
+    def __init__(
+        self,
+        duration: Union[int, ParameterExpression],
+        name: Optional[str] = None,
+        limit_amplitude: Optional[bool] = None,
+    ):
+        """Abstract base class for pulses
+        Args:
+            duration: Duration of the pulse
+            name: Optional name for the pulse
+            limit_amplitude: If ``True``, then limit the amplitude of the waveform to 1.
+                             The default value of ``None`` causes the flag value to be
+                             derived from :py:attr:`~limit_amplitude` which is ``True``
+                             by default but may be set by the user to disable amplitude
+                             checks globally.
+        """
+        if limit_amplitude is None:
+            limit_amplitude = self.__class__.limit_amplitude
+
+        self.duration = duration
+        self.name = name
+        self._limit_amplitude = limit_amplitude
+
+    @property
+    def id(self) -> int:  # pylint: disable=invalid-name
+        """Unique identifier for this pulse."""
+        return id(self)
+
+    @property
+    @abstractmethod
+    def parameters(self) -> Dict[str, Any]:
+        """Return a dictionary containing the pulse's parameters."""
+        pass
+
+    def is_parameterized(self) -> bool:
+        """Return True iff the instruction is parameterized."""
+        raise NotImplementedError
+
+    def draw(
+        self,
+        style: Optional[Dict[str, Any]] = None,
+        backend=None,  # importing backend causes cyclic import
+        time_range: Optional[Tuple[int, int]] = None,
+        time_unit: str = "dt",
+        show_waveform_info: bool = True,
+        plotter: str = "mpl2d",
+        axis: Optional[Any] = None,
+    ):
+        """Plot the interpolated envelope of pulse.
+
+        Args:
+            style: Stylesheet options. This can be dictionary or preset stylesheet classes. See
+                :py:class:`~qiskit.visualization.pulse_v2.stylesheets.IQXStandard`,
+                :py:class:`~qiskit.visualization.pulse_v2.stylesheets.IQXSimple`, and
+                :py:class:`~qiskit.visualization.pulse_v2.stylesheets.IQXDebugging` for details of
+                preset stylesheets.
+            backend (Optional[BaseBackend]): Backend object to play the input pulse program.
+                If provided, the plotter may use to make the visualization hardware aware.
+            time_range: Set horizontal axis limit. Tuple ``(tmin, tmax)``.
+            time_unit: The unit of specified time range either ``dt`` or ``ns``.
+                The unit of ``ns`` is available only when ``backend`` object is provided.
+            show_waveform_info: Show waveform annotations, i.e. name, of waveforms.
+                Set ``True`` to show additional information about waveforms.
+            plotter: Name of plotter API to generate an output image.
+                One of following APIs should be specified::
+
+                    mpl2d: Matplotlib API for 2D image generation.
+                        Matplotlib API to generate 2D image. Charts are placed along y axis with
+                        vertical offset. This API takes matplotlib.axes.Axes as `axis` input.
+
+                `axis` and `style` kwargs may depend on the plotter.
+            axis: Arbitrary object passed to the plotter. If this object is provided,
+                the plotters use a given ``axis`` instead of internally initializing
+                a figure object. This object format depends on the plotter.
+                See plotter argument for details.
+
+        Returns:
+            Visualization output data.
+            The returned data type depends on the ``plotter``.
+            If matplotlib family is specified, this will be a ``matplotlib.pyplot.Figure`` data.
+        """
+        # pylint: disable=cyclic-import
+        from qiskit.visualization import pulse_drawer
+
+        return pulse_drawer(
+            program=self,
+            style=style,
+            backend=backend,
+            time_range=time_range,
+            time_unit=time_unit,
+            show_waveform_info=show_waveform_info,
+            plotter=plotter,
+            axis=axis,
+        )
+
+    @abstractmethod
+    def __eq__(self, other: "Pulse") -> bool:
+        return isinstance(other, type(self))
+
+    @abstractmethod
+    def __hash__(self) -> int:
+        raise NotImplementedError
+
+    @abstractmethod
+    def __repr__(self) -> str:
+        raise NotImplementedError

qiskit/pulse/library/samplers/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+
+"""Module for methods which sample continuous functions."""
+
+from .decorators import left, right, midpoint

qiskit/pulse/library/samplers/decorators.py

@@ -0,0 +1,299 @@
+# 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.
+
+"""Sampler decorator module for sampling of continuous pulses to discrete pulses to be
+exposed to user.
+
+Some atypical boilerplate has been added to solve the problem of decorators not preserving
+their wrapped function signatures. Below we explain the problem that samplers solve and how
+we implement this.
+
+A sampler is a function that takes an continuous pulse function with signature:
+    ```python
+    def f(times: np.ndarray, *args, **kwargs) -> np.ndarray:
+        ...
+    ```
+and returns a new function:
+    def f(duration: int, *args, **kwargs) -> Waveform:
+        ...
+
+Samplers are used to build up pulse waveforms from continuous pulse functions.
+
+In Python the creation of a dynamic function that wraps another function will cause
+the underlying signature and documentation of the underlying function to be overwritten.
+In order to circumvent this issue the Python standard library provides the decorator
+`functools.wraps` which allows the programmer to expose the names and signature of the
+wrapped function as those of the dynamic function.
+
+Samplers are implemented by creating a function with signature
+    @sampler
+    def left(continuous_pulse: Callable, duration: int, *args, **kwargs)
+        ...
+
+This will create a sampler function for `left`. Since it is a dynamic function it would not
+have the docstring of `left` available too `help`. This could be fixed by wrapping with
+`functools.wraps` in the `sampler`, but this would then cause the signature to be that of the
+sampler function which is called on the continuous pulse, below:
+    `(continuous_pulse: Callable, duration: int, *args, **kwargs)``
+This is not correct for the sampler as the output sampled functions accept only a function.
+For the standard sampler we get around this by not using `functools.wraps` and
+explicitly defining our samplers such as `left`, `right` and `midpoint` and
+calling `sampler` internally on the function that implements the sampling schemes such as
+`left_sample`, `right_sample` and `midpoint_sample` respectively. See `left` for an example of this.
+
+
+In this way our standard samplers will expose the proper help signature, but a user can
+still create their own sampler with
+    @sampler
+    def custom_sampler(time, *args, **kwargs):
+        ...
+However, in this case it will be missing documentation of the underlying sampling methods.
+We believe that the definition of custom samplers will be rather infrequent.
+
+However, users will frequently apply sampler instances too continuous pulses. Therefore, a different
+approach was required for sampled continuous functions (the output of an continuous pulse function
+decorated by a sampler instance).
+
+A sampler instance is a decorator that may be used to wrap continuous pulse functions such as
+linear below:
+```python
+    @left
+    def linear(times: np.ndarray, m: float, b: float) -> np.ndarray:
+        ```Linear test function
+        Args:
+            times: Input times.
+            m: Slope.
+            b: Intercept
+        Returns:
+            np.ndarray
+        ```
+        return m*times+b
+```
+Which after decoration may be called with a duration rather than an array of times
+    ```python
+    duration = 10
+    pulse_envelope = linear(10, 0.1, 0.1)
+    ```
+If one calls help on `linear` they will find
+    ```
+    linear(duration:int, *args, **kwargs) -> numpy.ndarray
+    Discretized continuous pulse function: `linear` using
+    sampler: `_left`.
+
+     The first argument (time) of the continuous pulse function has been replaced with
+     a discretized `duration` of type (int).
+
+     Args:
+         duration (int)
+         *args: Remaining arguments of continuous pulse function.
+                See continuous pulse function documentation below.
+         **kwargs: Remaining kwargs of continuous pulse function.
+                   See continuous pulse function documentation below.
+
+     Sampled continuous function:
+
+        function linear in module test.python.pulse.test_samplers
+        linear(x:numpy.ndarray, m:float, b:float) -> numpy.ndarray
+            Linear test function
+            Args:
+                x: Input times.
+                m: Slope.
+                b: Intercept
+            Returns:
+                np.ndarray
+    ```
+This is partly because `functools.wraps` has been used on the underlying function.
+This in itself is not sufficient as the signature of the sampled function has
+`duration`, whereas the signature of the continuous function is `time`.
+
+This is achieved by removing `__wrapped__` set by `functools.wraps` in order to preserve
+the correct signature and also applying `_update_annotations` and `_update_docstring`
+to the generated function which corrects the function annotations and adds an informative
+docstring respectively.
+
+The user therefore has access to the correct sampled function docstring in its entirety, while
+still seeing the signature for the continuous pulse function and all of its arguments.
+"""
+
+import functools
+from typing import Callable
+import textwrap
+import pydoc
+
+import numpy as np
+
+from ...exceptions import PulseError
+from ..waveform import Waveform
+from . import strategies
+
+
+def functional_pulse(func: Callable) -> Callable:
+    """A decorator for generating Waveform from python callable.
+
+    Args:
+        func: A function describing pulse envelope.
+
+    Raises:
+        PulseError: when invalid function is specified.
+    """
+
+    @functools.wraps(func)
+    def to_pulse(duration, *args, name=None, **kwargs):
+        """Return Waveform."""
+        if isinstance(duration, (int, np.integer)) and duration > 0:
+            samples = func(duration, *args, **kwargs)
+            samples = np.asarray(samples, dtype=np.complex128)
+            return Waveform(samples=samples, name=name)
+        raise PulseError("The first argument must be an integer value representing duration.")
+
+    return to_pulse
+
+
+def _update_annotations(discretized_pulse: Callable) -> Callable:
+    """Update annotations of discretized continuous pulse function with duration.
+
+    Args:
+        discretized_pulse: Discretized decorated continuous pulse.
+    """
+    undecorated_annotations = list(discretized_pulse.__annotations__.items())
+    decorated_annotations = undecorated_annotations[1:]
+    decorated_annotations.insert(0, ("duration", int))
+    discretized_pulse.__annotations__ = dict(decorated_annotations)
+    return discretized_pulse
+
+
+def _update_docstring(discretized_pulse: Callable, sampler_inst: Callable) -> Callable:
+    """Update annotations of discretized continuous pulse function.
+
+    Args:
+        discretized_pulse: Discretized decorated continuous pulse.
+        sampler_inst: Applied sampler.
+    """
+    wrapped_docstring = pydoc.render_doc(discretized_pulse, "%s")
+    header, body = wrapped_docstring.split("\n", 1)
+    body = textwrap.indent(body, "                    ")
+    wrapped_docstring = header + body
+    updated_ds = """
+                Discretized continuous pulse function: `{continuous_name}` using
+                sampler: `{sampler_name}`.
+
+                 The first argument (time) of the continuous pulse function has been replaced with
+                 a discretized `duration` of type (int).
+
+                 Args:
+                     duration (int)
+                     *args: Remaining arguments of continuous pulse function.
+                            See continuous pulse function documentation below.
+                     **kwargs: Remaining kwargs of continuous pulse function.
+                               See continuous pulse function documentation below.
+
+                 Sampled continuous function:
+
+                    {continuous_doc}
+                """.format(
+        continuous_name=discretized_pulse.__name__,
+        sampler_name=sampler_inst.__name__,
+        continuous_doc=wrapped_docstring,
+    )
+
+    discretized_pulse.__doc__ = updated_ds
+    return discretized_pulse
+
+
+def sampler(sample_function: Callable) -> Callable:
+    """Sampler decorator base method.
+
+    Samplers are used for converting an continuous function to a discretized pulse.
+
+    They operate on a function with the signature:
+        `def f(times: np.ndarray, *args, **kwargs) -> np.ndarray`
+    Where `times` is a numpy array of floats with length n_times and the output array
+    is a complex numpy array with length n_times. The output of the decorator is an
+    instance of `FunctionalPulse` with signature:
+        `def g(duration: int, *args, **kwargs) -> Waveform`
+
+    Note if your continuous pulse function outputs a `complex` scalar rather than a
+    `np.ndarray`, you should first vectorize it before applying a sampler.
+
+
+    This class implements the sampler boilerplate for the sampler.
+
+    Args:
+        sample_function: A sampler function to be decorated.
+    """
+
+    def generate_sampler(continuous_pulse: Callable) -> Callable:
+        """Return a decorated sampler function."""
+
+        @functools.wraps(continuous_pulse)
+        def call_sampler(duration: int, *args, **kwargs) -> Waveform:
+            """Replace the call to the continuous function with a call to the sampler applied
+            to the analytic pulse function."""
+            sampled_pulse = sample_function(continuous_pulse, duration, *args, **kwargs)
+            return np.asarray(sampled_pulse, dtype=np.complex128)
+
+        # Update type annotations for wrapped continuous function to be discrete
+        call_sampler = _update_annotations(call_sampler)
+        # Update docstring with that of the sampler and include sampled function documentation.
+        call_sampler = _update_docstring(call_sampler, sample_function)
+        # Unset wrapped to return base sampler signature
+        # but still get rest of benefits of wraps
+        # such as __name__, __qualname__
+        call_sampler.__dict__.pop("__wrapped__")
+        # wrap with functional pulse
+        return functional_pulse(call_sampler)
+
+    return generate_sampler
+
+
+def left(continuous_pulse: Callable) -> Callable:
+    r"""Left sampling strategy decorator.
+
+    See `pulse.samplers.sampler` for more information.
+
+    For `duration`, return:
+        $$\{f(t) \in \mathbb{C} | t \in \mathbb{Z} \wedge  0<=t<\texttt{duration}\}$$
+
+    Args:
+        continuous_pulse: To sample.
+    """
+
+    return sampler(strategies.left_sample)(continuous_pulse)
+
+
+def right(continuous_pulse: Callable) -> Callable:
+    r"""Right sampling strategy decorator.
+
+    See `pulse.samplers.sampler` for more information.
+
+    For `duration`, return:
+        $$\{f(t) \in \mathbb{C} | t \in \mathbb{Z} \wedge  0<t<=\texttt{duration}\}$$
+
+    Args:
+        continuous_pulse: To sample.
+    """
+
+    return sampler(strategies.right_sample)(continuous_pulse)
+
+
+def midpoint(continuous_pulse: Callable) -> Callable:
+    r"""Midpoint sampling strategy decorator.
+
+    See `pulse.samplers.sampler` for more information.
+
+    For `duration`, return:
+        $$\{f(t+0.5) \in \mathbb{C} | t \in \mathbb{Z} \wedge  0<=t<\texttt{duration}\}$$
+
+    Args:
+        continuous_pulse: To sample.
+    """
+    return sampler(strategies.midpoint_sample)(continuous_pulse)

qiskit/pulse/library/samplers/strategies.py

@@ -0,0 +1,71 @@
+# 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.
+
+
+"""Sampler strategy module for sampler functions.
+
+Sampler functions have signature.
+    ```python
+    def sampler_function(continuous_pulse: Callable, duration: int, *args, **kwargs) -> np.ndarray:
+        ...
+    ```
+where the supplied `continuous_pulse` is a function with signature:
+    ```python
+    def f(times: np.ndarray, *args, **kwargs) -> np.ndarray:
+        ...
+    ```
+The sampler will call the `continuous_pulse` function with a set of times it will decide
+according to the sampling strategy it implements along with the passed `args` and `kwargs`.
+"""
+
+from typing import Callable
+
+import numpy as np
+
+
+def left_sample(continuous_pulse: Callable, duration: int, *args, **kwargs) -> np.ndarray:
+    """Left sample a continuous function.
+
+    Args:
+        continuous_pulse: Continuous pulse function to sample.
+        duration: Duration to sample for.
+        *args: Continuous pulse function args.
+        **kwargs: Continuous pulse function kwargs.
+    """
+    times = np.arange(duration)
+    return continuous_pulse(times, *args, **kwargs)
+
+
+def right_sample(continuous_pulse: Callable, duration: int, *args, **kwargs) -> np.ndarray:
+    """Sampling strategy for decorator.
+
+    Args:
+        continuous_pulse: Continuous pulse function to sample.
+        duration: Duration to sample for.
+        *args: Continuous pulse function args.
+        **kwargs: Continuous pulse function kwargs.
+    """
+    times = np.arange(1, duration + 1)
+    return continuous_pulse(times, *args, **kwargs)
+
+
+def midpoint_sample(continuous_pulse: Callable, duration: int, *args, **kwargs) -> np.ndarray:
+    """Sampling strategy for decorator.
+
+    Args:
+        continuous_pulse: Continuous pulse function to sample.
+        duration: Duration to sample for.
+        *args: Continuous pulse function args.
+        **kwargs: Continuous pulse function kwargs.
+    """
+    times = np.arange(1 / 2, duration + 1 / 2)
+    return continuous_pulse(times, *args, **kwargs)