iqm-pulse 11.2.0__py3-none-any.whl → 12.1.0__py3-none-any.whl

iqm/pulse/__init__.py

@@ -15,6 +15,9 @@
 
 from importlib.metadata import PackageNotFoundError, version
 
+from iqm.pulse.builder import CircuitOperation
+from iqm.pulse.circuit_operations import Circuit
+
 try:
     DIST_NAME = "iqm-pulse"
     __version__ = version(DIST_NAME)

iqm/pulse/builder.py

@@ -80,7 +80,36 @@ logger = logging.getLogger(__name__)
 
 @dataclass
 class CircuitOperation:
-    """Specific quantum operation applied on a specific part of the QPU, e.g. in a quantum circuit."""
+    r"""Specific quantum operation applied on a specific part of the QPU, e.g. in a quantum circuit.
+
+    We currently support the following native operations for circuit execution:
+
+    ================ =========== ======================================= ===========
+    name             # of qubits args                                    description
+    ================ =========== ======================================= ===========
+    measure          >= 1        ``key: str``, ``feedback_key: str``     Measurement in the Z basis.
+    prx              1           ``angle: float``, ``phase: float``      Phased x-rotation gate.
+    cc_prx           1           ``angle: float``, ``phase: float``,
+                                 ``feedback_qubit: str``,
+                                 ``feedback_key: str``                   Classically controlled PRX gate.
+    reset            >= 1                                                Reset the qubit(s) to :math:`|0\rangle`.
+    cz               2                                                   Controlled-Z gate.
+    move             2                                                   Move a qubit state between a qubit and a
+                                                                         computational resonator, as long as
+                                                                         at least one of the components is
+                                                                         in the :math:`|0\rangle` state.
+    barrier          >= 1                                                Execution barrier.
+    delay            >= 1        ``duration: float``                     Force a delay between circuit operations.
+    ================ =========== ======================================= ===========
+
+    For each CircuitOperation you may also optionally specify :attr:`implementation`,
+    which contains the name of an implementation of the operation to use.
+    Support for multiple implementations is currently experimental and in normal use the
+    field should be omitted, this selects the default implementation for the operation for that locus.
+
+    See the submodules under :mod:`iqm.pulse.gates` for more details about each operation.
+
+    """
 
     name: str
     """name of the quantum operation"""
@@ -101,31 +130,54 @@ class CircuitOperation:
             ValueError: operation is not valid
 
         """
-        # find the op type
         op_type = op_table.get(self.name)
         if op_type is None:
-            raise ValueError(f"Unknown quantum operation '{self.name}'.")
-
-        # find the implementation
-        impl_name = self.implementation
-        if impl_name is not None and impl_name not in op_type.implementations:
-            raise ValueError(f"Unknown implementation '{impl_name}' for quantum operation '{self.name}'.")
-
-        if 0 < op_type.arity != len(self.locus):
+            message = ", ".join(op_table)
+            raise ValueError(f"Unknown operation '{self.name}'. Supported operations are '{message}'.")
+        self._validate_implementation(op_type)
+        self._validate_locus(op_type)
+        self._validate_args(op_type)
+
+    def _validate_implementation(self, op_type: QuantumOp) -> None:
+        if self.implementation is not None:
+            if not self.implementation:
+                raise ValueError("Implementation of the instruction should be None, or a non-empty string")
+            if self.implementation not in op_type.implementations:
+                raise ValueError(f"Unknown implementation '{self.implementation}' for quantum operation '{self.name}'.")
+
+    def _validate_locus(self, op_type: QuantumOp) -> None:
+        arity = op_type.arity
+        if (0 < arity) and (arity != len(self.locus)):
             raise ValueError(
-                f"The '{self.name}' operation acts on {op_type.arity} qubit(s), "
-                f"but {len(self.locus)} were given: {self.locus}"
+                f"The '{self.name}' operation acts on {arity} qubit(s), but {len(self.locus)} were given: {self.locus}."
             )
-
         if len(self.locus) != len(set(self.locus)):
             raise ValueError(f"Repeated locus components: {self.locus}.")
 
-        if not set(op_type.params).issubset(self.args):
+    def _validate_args(self, op_type: QuantumOp) -> None:
+        # Check argument names
+        submitted_arg_names = set(self.args)
+        allowed_arg_types = op_type.params | op_type.optional_params
+        if not set(op_type.params) <= submitted_arg_names:
             raise ValueError(
-                f"The '{self.name}' operation requires the arguments {op_type.params}, "
-                f"but {tuple(self.args)} were given."
+                f"The operation '{self.name}' requires "
+                f"the argument(s) {tuple(op_type.params)}, "
+                f"but {tuple(submitted_arg_names)} were given."
             )
 
+        if not submitted_arg_names <= set(allowed_arg_types):
+            allowed_arg_names = tuple(allowed_arg_types)
+            message = f"the arguments {allowed_arg_names}" if allowed_arg_names else "no arguments"
+            raise ValueError(f"The operation '{self.name}' allows {message}, but {submitted_arg_names} were given.")
+        # Check argument types
+        for arg_name, arg_value in self.args.items():
+            allowed_types = allowed_arg_types[arg_name]
+            if not isinstance(arg_value, allowed_types):
+                raise ValueError(
+                    f"The argument '{arg_name}' should be of one of the following supported types"
+                    f" {allowed_types}, but ({type(arg_value)}) was given."
+                )
+
 
 def load_config(path: str) -> tuple[QuantumOpTable, OpCalibrationDataTree]:
     """Load quantum operation definitions and calibration data from a YAML config file.

iqm/pulse/circuit_operations.py

@@ -11,13 +11,14 @@ from __future__ import annotations
 
 from collections import Counter
 from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
 from functools import lru_cache
-from typing import Self
+from typing import Any, Self
 
 import numpy as np
 
 from iqm.pulse.builder import CircuitOperation, build_quantum_ops
-from iqm.pulse.quantum_ops import QuantumOpTable
+from iqm.pulse.quantum_ops import QuantumOp, QuantumOpTable
 
 
 def reorder(A: np.ndarray, perm: list[int]) -> np.ndarray:
@@ -363,8 +364,15 @@ class CircuitOperationList(list):
         params = self.table[name].params
         if len(params) != len(args):
             raise TypeError(
-                f"Operation {name} has the following arguments: {params}, but {len(args)} values were provided."
+                f"Operation {name} has the following arguments: {tuple(params)}, but {len(args)} values were provided."
             )
+        # Convert int args to floats, so that one can pass e.g. 0 instead of 0.0 for the arg.
+        # Note that this conversion is not exact if the int value is too large, but such values are not realistic
+        # for the current parameter types.
+        args = tuple(
+            float(arg) if (float in param_types and int not in param_types) and isinstance(arg, int) else arg
+            for arg, param_types in zip(args, params.values())
+        )
         new_op = CircuitOperation(name=name, args=dict(zip(params, args)), implementation=impl_name, locus=locus)
         new_op.validate(self.table)
         self.append(new_op)
@@ -503,3 +511,55 @@ class CircuitOperationList(list):
             f" optionally to fix the implementation of the operation in iqm-pulse."
         )
         setattr(CircuitOperationList, name, _add_specific_op)
+
+
+@dataclass
+class Circuit:
+    """Quantum circuit.
+
+    Used e.g. for client-server communication.
+
+    Consists of a sequence of native quantum operations, each represented by an instance of the
+    :class:`CircuitOperation` class.
+    """
+
+    name: str
+    """name of the circuit"""
+    instructions: tuple[CircuitOperation, ...]
+    """operations comprising the circuit"""
+    metadata: dict[str, Any] | None = None
+    """optional metadata for the circuit"""
+
+    def all_locus_components(self) -> set[str]:
+        """Return the names of all locus components (typically qubits) in the circuit."""
+        components: set[str] = set()
+        for instruction in self.instructions:
+            components.update(instruction.locus)
+        return components
+
+    def validate(self, supported_operations: dict[str, QuantumOp]) -> None:
+        """Validate the circuit against the supported quantum operations.
+
+        Args:
+            supported_operations: mapping of supported quantum operation names to their definitions
+
+        Raises:
+            ValueError: circuit is not valid
+
+        """
+        self._validate_name()
+        self._validate_instructions(supported_operations)
+
+    def _validate_name(self) -> None:
+        if not self.name:
+            raise ValueError("A circuit should have a non-empty string for a name.")
+
+    def _validate_instructions(self, supported_operations: dict[str, QuantumOp]) -> None:
+        if not self.instructions:
+            raise ValueError("Each circuit should have at least one instruction.")
+
+        for instruction in self.instructions:
+            if isinstance(instruction, CircuitOperation):
+                instruction.validate(supported_operations)
+            else:
+                raise ValueError("Every instruction in a circuit should be of type <CircuitOperation>")

iqm/pulse/gates/default_gates.py

@@ -125,41 +125,52 @@ _quantum_ops_library = {
         QuantumOp(
             "delay",
             0,
-            ("duration",),
+            {"duration": (float,)},
             implementations=_implementation_library["delay"],
             symmetric=True,
         ),
         QuantumOp(
             "measure",
             0,
-            ("key",),
+            {"key": (str,)},
+            optional_params={"feedback_key": (str,)},
             implementations=_implementation_library["measure"],
             factorizable=True,
         ),
         QuantumOp(
             "measure_fidelity",
             0,
-            ("key",),
+            {"key": (str,)},
             implementations=_implementation_library["measure_fidelity"],
             factorizable=True,
         ),
         QuantumOp(
             "prx",
             1,
-            ("angle", "phase"),
+            {
+                "angle": (float,),
+                "phase": (float,),
+            },
             implementations=_implementation_library["prx"],
             unitary=get_unitary_prx,
         ),
         QuantumOp(
             "prx_12",
             1,
-            ("angle", "phase"),
+            {
+                "angle": (float,),
+                "phase": (float,),
+            },
             implementations=_implementation_library["prx_12"],
         ),
         QuantumOp(
             "u",
             1,
-            ("theta", "phi", "lam"),
+            {
+                "theta": (float,),
+                "phi": (float,),
+                "lam": (float,),
+            },
             implementations=_implementation_library["u"],
             unitary=get_unitary_u,
         ),
@@ -172,7 +183,7 @@ _quantum_ops_library = {
         QuantumOp(
             "rz",
             1,
-            ("angle",),
+            {"angle": (float,)},
             implementations=_implementation_library["rz"],
             unitary=get_unitary_rz,
         ),
@@ -184,7 +195,7 @@ _quantum_ops_library = {
         QuantumOp(
             "cz",
             2,
-            (),
+            {},
             implementations=_implementation_library["cz"],
             symmetric=True,
             unitary=lambda: np.diag([1.0, 1.0, 1.0, -1.0]),
@@ -197,7 +208,12 @@ _quantum_ops_library = {
         QuantumOp(
             "cc_prx",
             1,
-            ("angle", "phase", "feedback_qubit", "feedback_key"),
+            {
+                "angle": (float,),
+                "phase": (float,),
+                "feedback_qubit": (str,),
+                "feedback_key": (str,),
+            },
             implementations=_implementation_library["cc_prx"],
         ),
         QuantumOp(

iqm/pulse/quantum_ops.py

@@ -78,8 +78,10 @@ class QuantumOp:
     Each locus component corresponds to a quantum subsystem in the definition of the operation.
     The computational subspace always consists of the lowest two levels of the subsystem.
     Zero means the operation can be applied on any number of locus components."""
-    params: tuple[str, ...] = ()
-    """Names of required operation parameters, if any."""
+    params: dict[str, tuple[type, ...]] = field(default_factory=dict)
+    """Maps names of required operation parameters to their allowed types."""
+    optional_params: dict[str, tuple[type, ...]] = field(default_factory=dict)
+    """Maps names of optional operation parameters to their allowed types."""
     implementations: dict[str, type[GateImplementation]] = field(default_factory=dict)
     """Maps implementation names to :class:`.GateImplementation` classes that provide them.
     Each such class should describe the implementation in detail in its docstring.
@@ -100,7 +102,8 @@ class QuantumOp:
     """Unitary matrix that represents the effect of this quantum operation in the computational basis, or ``None``
     if the quantum operation is not unitary or the exact unitary is not known.
     The Callable needs to take exactly the arguments given in :attr:`params`, for example if
-    ``params=('angle','phase')``, the function must have signature ``f(angle:float, phase: float) -> np.ndarray``.
+    ``params={'angle': (float,), 'phase': (float,)}``, the function must have signature 
+    ``f(angle: float, phase: float) -> np.ndarray``.
     For operations acting on more than 1 qubit, unitary should be given in the big-endian order, i.e. in the basis
     ``np.kron(first_qubit_basis_ket, second_qubit_basis_ket)``."""
 

{iqm_pulse-11.2.0.dist-info → iqm_pulse-12.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-pulse
-Version: 11.2.0
+Version: 12.1.0
 Summary: A Python-based project for providing interface and implementations for control pulses.
 Author-email: IQM Finland Oy <info@meetiqm.com>
 License: Apache License
@@ -213,7 +213,7 @@ Classifier: Intended Audience :: Science/Research
 Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
-Requires-Dist: iqm-exa-common <27,>=26
+Requires-Dist: iqm-exa-common <28,>=27
 Requires-Dist: iqm-data-definitions <3.0,>=2.13
 Requires-Dist: python-rapidjson ==1.20
 Requires-Dist: jinja2 ==3.0.3

{iqm_pulse-11.2.0.dist-info → iqm_pulse-12.1.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-iqm/pulse/__init__.py,sha256=FxgHlv3bF8bQCREwOJ1yu_nsrfJq0g0HdovvT1wUnCI,881
+iqm/pulse/__init__.py,sha256=aQhtfbLQgr_1IvbZLH1MCuf0aFomokeu7DSjxuDWZC4,978
 iqm/pulse/base_utils.py,sha256=ll3k8wbVxjHi6XcVo3PEWIjHx5QjG1C-yH218zTG8jU,2657
-iqm/pulse/builder.py,sha256=MhBAw2NHTDGR79ARGGF44EkGDxaXlp6KHoNnPEQuyEY,74712
-iqm/pulse/circuit_operations.py,sha256=V568uC2LJBs6BlDbioQCh9iCBYhgkTiAbto9VSbmTgQ,22499
+iqm/pulse/builder.py,sha256=uL2MsAvRs1dJfe2mVNrrHEqUoBBTJlABt0KmBtB6hl0,78294
+iqm/pulse/circuit_operations.py,sha256=P83gevhGcaY4DaopGKO3CHN_CnWAPfEu-MHoLkqhu5Y,24847
 iqm/pulse/gate_implementation.py,sha256=yyj2d1aDL0K_qouo0qLHnZ49_1qHsJEShKW14398t8Q,39546
 iqm/pulse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-iqm/pulse/quantum_ops.py,sha256=UTQ08Eo5vFpV_lOoQNtlwRTchES6BdGHQ5pzSdb1ToY,14584
+iqm/pulse/quantum_ops.py,sha256=cV13V1t2rj9lgNKXgGZXMcNgEPJ7oraHL6eJJTlLvWk,14825
 iqm/pulse/scheduler.py,sha256=62gH3AcxmsgmShcmtNaiCqFLRl1Wll6Q24zIkhw_-XM,22768
 iqm/pulse/timebox.py,sha256=Yi8I43KiSPs2s_l1r0rMVm4mw0EpSCrpq3BCUNk5vyE,16618
 iqm/pulse/utils.py,sha256=0J4KQNvKtZahme7sP7vLa1FtENepC-eb9_A5WaghvVU,3710
@@ -13,7 +13,7 @@ iqm/pulse/gates/__init__.py,sha256=l07iD52FiKKQyVFwswRapZMqEE0XfILSc4aZ5sXGJo4,8
 iqm/pulse/gates/barrier.py,sha256=WhYV70lf4lh4Wa9UZuMk2lp9JbUQIu8lzewRC2P7pNE,2546
 iqm/pulse/gates/conditional.py,sha256=NE-1GYlFcfaCmRuhqGEIhtoJmBArhyY5KhVnO4y4zng,6289
 iqm/pulse/gates/cz.py,sha256=72KO8OINZRVOye4g4quHAEzwNplOlIZE0hU1IjE8Gfk,33366
-iqm/pulse/gates/default_gates.py,sha256=G76Nz2XAuwH2i5KIrzSp4pTBSbe9vcAjfT12PfPYMYA,7645
+iqm/pulse/gates/default_gates.py,sha256=JwdrCh_Blee4mMWZ8v8ymw3Ep0fZBvw9wuaLR3rjDXA,8073
 iqm/pulse/gates/delay.py,sha256=nST9dY2JFp_mpKhiSfsYa5yL4hFKcNJSAyCzXjhauQg,3767
 iqm/pulse/gates/enums.py,sha256=ATwb6vZYpfgQ1gQyFPW53JyIKrdAP3FPHm6jV-t9OAk,2532
 iqm/pulse/gates/flux_multiplexer.py,sha256=sk84ItEvkx7Z0pCHt8MCCczBe7_BHNvqS4_oeNghZw8,9757
@@ -39,8 +39,8 @@ iqm/pulse/playlist/visualisation/templates/static/logo.png,sha256=rbfQZ6_UEaztpY
 iqm/pulse/playlist/visualisation/templates/static/moment.min.js,sha256=4iQZ6BVL4qNKlQ27TExEhBN1HFPvAvAMbFavKKosSWQ,53324
 iqm/pulse/playlist/visualisation/templates/static/vis-timeline-graph2d.min.css,sha256=svzNasPg1yR5gvEaRei2jg-n4Pc3sVyMUWeS6xRAh6U,19837
 iqm/pulse/playlist/visualisation/templates/static/vis-timeline-graph2d.min.js,sha256=OqCqCyA6JnxPz3PGXq_P_9VuSqWptgNt5Ev3T-xjefQ,570288
-iqm_pulse-11.2.0.dist-info/LICENSE.txt,sha256=R6Q7eUrLyoCQgWYorQ8WJmVmWKYU3dxA3jYUp0wwQAw,11332
-iqm_pulse-11.2.0.dist-info/METADATA,sha256=LwwqFnDeeW1USz6YKNHEJjkxIkkwenUhpOV0UmvOwIg,14551
-iqm_pulse-11.2.0.dist-info/WHEEL,sha256=y4mX-SOX4fYIkonsAGA5N0Oy-8_gI4FXw5HNI1xqvWg,91
-iqm_pulse-11.2.0.dist-info/top_level.txt,sha256=NB4XRfyDS6_wG9gMsyX-9LTU7kWnTQxNvkbzIxGv3-c,4
-iqm_pulse-11.2.0.dist-info/RECORD,,
+iqm_pulse-12.1.0.dist-info/LICENSE.txt,sha256=R6Q7eUrLyoCQgWYorQ8WJmVmWKYU3dxA3jYUp0wwQAw,11332
+iqm_pulse-12.1.0.dist-info/METADATA,sha256=1DUFvxXliKMNqyJIFb_LVrTQnupzgw3Erhy0BZTN4k4,14551
+iqm_pulse-12.1.0.dist-info/WHEEL,sha256=y4mX-SOX4fYIkonsAGA5N0Oy-8_gI4FXw5HNI1xqvWg,91
+iqm_pulse-12.1.0.dist-info/top_level.txt,sha256=NB4XRfyDS6_wG9gMsyX-9LTU7kWnTQxNvkbzIxGv3-c,4
+iqm_pulse-12.1.0.dist-info/RECORD,,